module documentation

defmodule Cards do
	@moduledoc """
		Provides methods for creating and handling a deck of cards

	"""

	@doc """
		Returns a list of strings representing a deck of playing cards
	"""
	def create_deck do
		...
	end
	
	
@doc """
	Divides a deck into a hand and the remainder of deck. `hand_size` is argument.

## Examples

		iex> deck = Cards.create_deck
		iex> {hand, deck} = Cards.deal(deck, 1)
		iex> hand
		["Ace of Spades"]

		// These examples should have 3 tabs.
	
"""
def deal(deck, hand_size) do
	Enum.split(deck, hand_size)
end

end

defmodule Cards.Mixfile do
	use Mix.Project

	def project do
		[app: :cards,
		version: "0.1.0",
		elixir: "~> 1.3",
		build_embedded: Mix.env == :prod,
		start_permanent: Mix.env == :prod,
		deps: deps()]

	def application do
		[applications: [:logger]]
	end

	#List of all the dependencies!
	defp deps do
		[
		{:ex_doc, "~> 0.12"}
		]
	end
end

You can install dependencies by the command below.

mix deps.get

You can generate HTML documentation file if you have written @moduledoc

mix docs

Function documenation

When thefunction documentation with example is well written, then it has a great interaction with testing.

# This is just a copy from the top example.

@doc """
	Divides a deck into a hand and the remainder of deck. `hand_size` is argument.

## Examples

		iex> deck = Cards.create_deck
		iex> {hand, deck} = Cards.deal(deck, 1)
		iex> hand
		["Ace of Spades"]

		// These examples should have 3 tabs.
	
"""

Testing

mix test

How to write the additional test?

defmodule CardsTest do
	use ExUnit.Case
	doctest Cards

	## This is the **first type** of test (Insertion of particular case)
	test "the truth" do
		assert 1 + 1 == 3
	end
end

• What is Doctesting? : if test see the Examples in defmodule or def docs, it runs the test. —> so, documentation for other developer work as testing!

defmodule CardsTest do
	use ExUnit.Case
	doctest Cards # this lines run all the test inside the doc.
end

• Function Testing —> You run the script in the shell, and copy & paste how it’s printed in the terminal.

@doc """
	Determines whether a deck contians a given card
## Examples

		iex> deck = Cards.create_deck  # just get rid of the line of number after pasting.
		# ["Ace of Spaces", ... ] # but I don't need this line because it is the test of contains?
		iex> Cards.contains?(deck, "Ace of Spades")
		true
"""
def containes?(deck, card) do
	Enum.member?(deck, card)
end

• Case Tests

defmodule CardsTest do
	use ExUnit.Case
	doctest Cards # this lines run all the test inside the doc.

	test "create_deck makes 20 cards" do
		deck_length = length(Cards.create_deck)
		assert deck_length == 21
	end

	test "shuffling a deck randomizes it" do
		deck = Cards.create_deck
		assert deck != Cards.shuffle(deck)
		refute deck == Cards.shuffle(deck) # this is the exactly the same line above.
	end
end