{"action":"created","comment":{"url":"https://api.github.com/repos/doomspork/elixir-school/pulls/comments/58021709","id":58021709,"diff_hunk":"@@ -0,0 +1,351 @@\n+---\n+layout: page\n+title: Documentation\n+category: basics\n+order: 11\n+lang: fr\n+---\n+\n+Documenter du code Elixir.\n+\n+## Table des Matières.\n+\n+- [Annotations](#annotations)\n+  - [La documentation linéaire](#documentation-lineaire)\n+  - [Documenter les modules](#documenter-les-modules)\n+  - [Documenter les fonctions](#documenter-les-fonctions)\n+- [ExDoc](#exdoc)\n+  - [Installer](#installer)\n+  - [Générer la documentation](#generer-la-documentation)\n+- [Les bonnes pratiques](#les-bonnes-pratiques)\n+\n+\n+## Annotations\n+\n+La quantité de commentaires et les tenants d'une documentation de qualité demeurent un sujet problématique au sein du monde de la programmation.\n+Néanmoins, nous pouvons tous être d'accord que la documentation est importante, autant pour nous-même que pour les personnes amenées à travailler avec\n+notre code.\n+\n+Elixir traite la documentation comme une *citoyenne de premier ordre*, et offre de multiples fonctions pour accéder et générer de la documentation\n+pour vos projets. La bibliothèque standard d'Elixir fourni différents attributs pour annoter un code source. Examinons trois d'entre eux :\n+  - `#` - Pour la documentation linéaire.\n+  - `@moduledoc` - Pour la documentation à l'échelle d'un module.\n+  - `@doc` - Pour la documentation à l'échelle d'une fonction.\n+\n+### La documentation linéaire\n+\n+C'est probablement la façon la plus simple de commenter votre code. De façon similaire à Ruby ou Python, les commentaire d'Elixir sont marqués du symbole\n+`#` appelé *hash*, ou *croisillon* en Français.\n+\n+Prenez ce script en Elixir (greeting.exs) :\n+\n+```elixir\n+# Affiche \"Hello, chum.\" dans la console.\n+IO.puts \"Hello, \" <> \"chum.\"\n+```\n+\n+En executant ce script, Elixir va tout ignorer depuis le `#` jusqu'à la fin de la ligne. Néanmoins, même si cela n'ajoute aucune valeur à l'opération\n+d'execution et n'améliore pas les performances, une développeuse ou un développeur devrait pouvoir comprendre son fonctionnement en lisant votre commentaire.\n+Mais faites attention à ne pas en abuser !\n+\n+### Documenter les modules\n+\n+L'annotateur `@moduledoc` permet d'écrire de la documentation à l'échelle d'un module. Il est utilisé juste en dessous de la déclaration `defmodule`\n+au début du fichier. L'exemple ci-dessous montre un commentaire au sein de l'annotateur `moduledoc` :\n+\n+```elixir\n+defmodule Greeter do\n+  @moduledoc \"\"\"\n+  Fourni une fonction `hello/1` pour saluer un être humain\n+  \"\"\"\n+\n+  def hello(name) do\n+    \"Hello, \" <> name\n+  end\n+end\n+```\n+\n+Nous (ou d'autres personnes) pouvons accéder à cette documentation en utilisant le helper `h` dans la console IEx.\n+\n+```elixir\n+iex> c(\"greeter.ex\")\n+[Greeter]\n+\n+iex> h Greeter\n+\n+                Greeter\n+\n+Fourni une fonction `hello/1` pour saluer un être humain\n+```\n+\n+### Documenter les fonctions\n+\n+Just as Elixir gives us the ability for module level annotation, it also enables similar annotations for documenting functions. The `@doc` annotator allows for inline doc\n+umentation at a function level. The `@doc` annotator sits just above the function it is annotating.\n+Elixir nous permet également d'écrire de la documentation pour les fonctions : L'annotateur `@doc`, qui se situe juste avant la fonction concernée.","path":"fr/lessons/basics/documentation.md","position":85,"original_position":85,"commit_id":"4105a0b5f18b1fecbb684c7a55ee6d9ea0fb8674","original_commit_id":"4105a0b5f18b1fecbb684c7a55ee6d9ea0fb8674","user":{"login":"julienXX","id":53949,"avatar_url":"https://avatars.githubusercontent.com/u/53949?v=3","gravatar_id":"","url":"https://api.github.com/users/julienXX","html_url":"https://github.com/julienXX","followers_url":"https://api.github.com/users/julienXX/followers","following_url":"https://api.github.com/users/julienXX/following{/other_user}","gists_url":"https://api.github.com/users/julienXX/gists{/gist_id}","starred_url":"https://api.github.com/users/julienXX/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/julienXX/subscriptions","organizations_url":"https://api.github.com/users/julienXX/orgs","repos_url":"https://api.github.com/users/julienXX/repos","events_url":"https://api.github.com/users/julienXX/events{/privacy}","received_events_url":"https://api.github.com/users/julienXX/received_events","type":"User","site_admin":false},"body":"Un point plutôt que ':' ?","created_at":"2016-03-31T09:10:33Z","updated_at":"2016-03-31T09:10:33Z","html_url":"https://github.com/doomspork/elixir-school/pull/244#discussion_r58021709","pull_request_url":"https://api.github.com/repos/doomspork/elixir-school/pulls/244","_links":{"self":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/comments/58021709"},"html":{"href":"https://github.com/doomspork/elixir-school/pull/244#discussion_r58021709"},"pull_request":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/244"}}},"pull_request":{"url":"https://api.github.com/repos/doomspork/elixir-school/pulls/244","id":64703660,"html_url":"https://github.com/doomspork/elixir-school/pull/244","diff_url":"https://github.com/doomspork/elixir-school/pull/244.diff","patch_url":"https://github.com/doomspork/elixir-school/pull/244.patch","issue_url":"https://api.github.com/repos/doomspork/elixir-school/issues/244","number":244,"state":"open","locked":false,"title":"[FR] Translation for documentation.md","user":{"login":"tchoutri","id":15848443,"avatar_url":"https://avatars.githubusercontent.com/u/15848443?v=3","gravatar_id":"","url":"https://api.github.com/users/tchoutri","html_url":"https://github.com/tchoutri","followers_url":"https://api.github.com/users/tchoutri/followers","following_url":"https://api.github.com/users/tchoutri/following{/other_user}","gists_url":"https://api.github.com/users/tchoutri/gists{/gist_id}","starred_url":"https://api.github.com/users/tchoutri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tchoutri/subscriptions","organizations_url":"https://api.github.com/users/tchoutri/orgs","repos_url":"https://api.github.com/users/tchoutri/repos","events_url":"https://api.github.com/users/tchoutri/events{/privacy}","received_events_url":"https://api.github.com/users/tchoutri/received_events","type":"User","site_admin":false},"body":"@julienXX Please could you review this one? :)","created_at":"2016-03-30T21:53:17Z","updated_at":"2016-03-31T09:10:33Z","closed_at":null,"merged_at":null,"merge_commit_sha":"484c201591d8512fbb3a24e06e8ff3e3aa16cc1c","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/doomspork/elixir-school/pulls/244/commits","review_comments_url":"https://api.github.com/repos/doomspork/elixir-school/pulls/244/comments","review_comment_url":"https://api.github.com/repos/doomspork/elixir-school/pulls/comments{/number}","comments_url":"https://api.github.com/repos/doomspork/elixir-school/issues/244/comments","statuses_url":"https://api.github.com/repos/doomspork/elixir-school/statuses/4105a0b5f18b1fecbb684c7a55ee6d9ea0fb8674","head":{"label":"tchoutri:patch-1","ref":"patch-1","sha":"4105a0b5f18b1fecbb684c7a55ee6d9ea0fb8674","user":{"login":"tchoutri","id":15848443,"avatar_url":"https://avatars.githubusercontent.com/u/15848443?v=3","gravatar_id":"","url":"https://api.github.com/users/tchoutri","html_url":"https://github.com/tchoutri","followers_url":"https://api.github.com/users/tchoutri/followers","following_url":"https://api.github.com/users/tchoutri/following{/other_user}","gists_url":"https://api.github.com/users/tchoutri/gists{/gist_id}","starred_url":"https://api.github.com/users/tchoutri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tchoutri/subscriptions","organizations_url":"https://api.github.com/users/tchoutri/orgs","repos_url":"https://api.github.com/users/tchoutri/repos","events_url":"https://api.github.com/users/tchoutri/events{/privacy}","received_events_url":"https://api.github.com/users/tchoutri/received_events","type":"User","site_admin":false},"repo":{"id":54599451,"name":"elixir-school","full_name":"tchoutri/elixir-school","owner":{"login":"tchoutri","id":15848443,"avatar_url":"https://avatars.githubusercontent.com/u/15848443?v=3","gravatar_id":"","url":"https://api.github.com/users/tchoutri","html_url":"https://github.com/tchoutri","followers_url":"https://api.github.com/users/tchoutri/followers","following_url":"https://api.github.com/users/tchoutri/following{/other_user}","gists_url":"https://api.github.com/users/tchoutri/gists{/gist_id}","starred_url":"https://api.github.com/users/tchoutri/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tchoutri/subscriptions","organizations_url":"https://api.github.com/users/tchoutri/orgs","repos_url":"https://api.github.com/users/tchoutri/repos","events_url":"https://api.github.com/users/tchoutri/events{/privacy}","received_events_url":"https://api.github.com/users/tchoutri/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/tchoutri/elixir-school","description":"Lessons about the Elixir programming language","fork":true,"url":"https://api.github.com/repos/tchoutri/elixir-school","forks_url":"https://api.github.com/repos/tchoutri/elixir-school/forks","keys_url":"https://api.github.com/repos/tchoutri/elixir-school/keys{/key_id}","collaborators_url":"https://api.github.com/repos/tchoutri/elixir-school/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/tchoutri/elixir-school/teams","hooks_url":"https://api.github.com/repos/tchoutri/elixir-school/hooks","issue_events_url":"https://api.github.com/repos/tchoutri/elixir-school/issues/events{/number}","events_url":"https://api.github.com/repos/tchoutri/elixir-school/events","assignees_url":"https://api.github.com/repos/tchoutri/elixir-school/assignees{/user}","branches_url":"https://api.github.com/repos/tchoutri/elixir-school/branches{/branch}","tags_url":"https://api.github.com/repos/tchoutri/elixir-school/tags","blobs_url":"https://api.github.com/repos/tchoutri/elixir-school/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/tchoutri/elixir-school/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/tchoutri/elixir-school/git/refs{/sha}","trees_url":"https://api.github.com/repos/tchoutri/elixir-school/git/trees{/sha}","statuses_url":"https://api.github.com/repos/tchoutri/elixir-school/statuses/{sha}","languages_url":"https://api.github.com/repos/tchoutri/elixir-school/languages","stargazers_url":"https://api.github.com/repos/tchoutri/elixir-school/stargazers","contributors_url":"https://api.github.com/repos/tchoutri/elixir-school/contributors","subscribers_url":"https://api.github.com/repos/tchoutri/elixir-school/subscribers","subscription_url":"https://api.github.com/repos/tchoutri/elixir-school/subscription","commits_url":"https://api.github.com/repos/tchoutri/elixir-school/commits{/sha}","git_commits_url":"https://api.github.com/repos/tchoutri/elixir-school/git/commits{/sha}","comments_url":"https://api.github.com/repos/tchoutri/elixir-school/comments{/number}","issue_comment_url":"https://api.github.com/repos/tchoutri/elixir-school/issues/comments{/number}","contents_url":"https://api.github.com/repos/tchoutri/elixir-school/contents/{+path}","compare_url":"https://api.github.com/repos/tchoutri/elixir-school/compare/{base}...{head}","merges_url":"https://api.github.com/repos/tchoutri/elixir-school/merges","archive_url":"https://api.github.com/repos/tchoutri/elixir-school/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/tchoutri/elixir-school/downloads","issues_url":"https://api.github.com/repos/tchoutri/elixir-school/issues{/number}","pulls_url":"https://api.github.com/repos/tchoutri/elixir-school/pulls{/number}","milestones_url":"https://api.github.com/repos/tchoutri/elixir-school/milestones{/number}","notifications_url":"https://api.github.com/repos/tchoutri/elixir-school/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/tchoutri/elixir-school/labels{/name}","releases_url":"https://api.github.com/repos/tchoutri/elixir-school/releases{/id}","deployments_url":"https://api.github.com/repos/tchoutri/elixir-school/deployments","created_at":"2016-03-23T23:13:50Z","updated_at":"2016-03-23T23:13:51Z","pushed_at":"2016-03-30T21:52:52Z","git_url":"git://github.com/tchoutri/elixir-school.git","ssh_url":"git@github.com:tchoutri/elixir-school.git","clone_url":"https://github.com/tchoutri/elixir-school.git","svn_url":"https://github.com/tchoutri/elixir-school","homepage":"https://elixirschool.com","size":852,"stargazers_count":0,"watchers_count":0,"language":"CSS","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"doomspork:master","ref":"master","sha":"4a9eebe7dc325bbee3a956e604bf19f0d8c16a3b","user":{"login":"doomspork","id":73386,"avatar_url":"https://avatars.githubusercontent.com/u/73386?v=3","gravatar_id":"","url":"https://api.github.com/users/doomspork","html_url":"https://github.com/doomspork","followers_url":"https://api.github.com/users/doomspork/followers","following_url":"https://api.github.com/users/doomspork/following{/other_user}","gists_url":"https://api.github.com/users/doomspork/gists{/gist_id}","starred_url":"https://api.github.com/users/doomspork/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/doomspork/subscriptions","organizations_url":"https://api.github.com/users/doomspork/orgs","repos_url":"https://api.github.com/users/doomspork/repos","events_url":"https://api.github.com/users/doomspork/events{/privacy}","received_events_url":"https://api.github.com/users/doomspork/received_events","type":"User","site_admin":false},"repo":{"id":36616176,"name":"elixir-school","full_name":"doomspork/elixir-school","owner":{"login":"doomspork","id":73386,"avatar_url":"https://avatars.githubusercontent.com/u/73386?v=3","gravatar_id":"","url":"https://api.github.com/users/doomspork","html_url":"https://github.com/doomspork","followers_url":"https://api.github.com/users/doomspork/followers","following_url":"https://api.github.com/users/doomspork/following{/other_user}","gists_url":"https://api.github.com/users/doomspork/gists{/gist_id}","starred_url":"https://api.github.com/users/doomspork/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/doomspork/subscriptions","organizations_url":"https://api.github.com/users/doomspork/orgs","repos_url":"https://api.github.com/users/doomspork/repos","events_url":"https://api.github.com/users/doomspork/events{/privacy}","received_events_url":"https://api.github.com/users/doomspork/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/doomspork/elixir-school","description":"Lessons about the Elixir programming language","fork":false,"url":"https://api.github.com/repos/doomspork/elixir-school","forks_url":"https://api.github.com/repos/doomspork/elixir-school/forks","keys_url":"https://api.github.com/repos/doomspork/elixir-school/keys{/key_id}","collaborators_url":"https://api.github.com/repos/doomspork/elixir-school/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/doomspork/elixir-school/teams","hooks_url":"https://api.github.com/repos/doomspork/elixir-school/hooks","issue_events_url":"https://api.github.com/repos/doomspork/elixir-school/issues/events{/number}","events_url":"https://api.github.com/repos/doomspork/elixir-school/events","assignees_url":"https://api.github.com/repos/doomspork/elixir-school/assignees{/user}","branches_url":"https://api.github.com/repos/doomspork/elixir-school/branches{/branch}","tags_url":"https://api.github.com/repos/doomspork/elixir-school/tags","blobs_url":"https://api.github.com/repos/doomspork/elixir-school/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/doomspork/elixir-school/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/doomspork/elixir-school/git/refs{/sha}","trees_url":"https://api.github.com/repos/doomspork/elixir-school/git/trees{/sha}","statuses_url":"https://api.github.com/repos/doomspork/elixir-school/statuses/{sha}","languages_url":"https://api.github.com/repos/doomspork/elixir-school/languages","stargazers_url":"https://api.github.com/repos/doomspork/elixir-school/stargazers","contributors_url":"https://api.github.com/repos/doomspork/elixir-school/contributors","subscribers_url":"https://api.github.com/repos/doomspork/elixir-school/subscribers","subscription_url":"https://api.github.com/repos/doomspork/elixir-school/subscription","commits_url":"https://api.github.com/repos/doomspork/elixir-school/commits{/sha}","git_commits_url":"https://api.github.com/repos/doomspork/elixir-school/git/commits{/sha}","comments_url":"https://api.github.com/repos/doomspork/elixir-school/comments{/number}","issue_comment_url":"https://api.github.com/repos/doomspork/elixir-school/issues/comments{/number}","contents_url":"https://api.github.com/repos/doomspork/elixir-school/contents/{+path}","compare_url":"https://api.github.com/repos/doomspork/elixir-school/compare/{base}...{head}","merges_url":"https://api.github.com/repos/doomspork/elixir-school/merges","archive_url":"https://api.github.com/repos/doomspork/elixir-school/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/doomspork/elixir-school/downloads","issues_url":"https://api.github.com/repos/doomspork/elixir-school/issues{/number}","pulls_url":"https://api.github.com/repos/doomspork/elixir-school/pulls{/number}","milestones_url":"https://api.github.com/repos/doomspork/elixir-school/milestones{/number}","notifications_url":"https://api.github.com/repos/doomspork/elixir-school/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/doomspork/elixir-school/labels{/name}","releases_url":"https://api.github.com/repos/doomspork/elixir-school/releases{/id}","deployments_url":"https://api.github.com/repos/doomspork/elixir-school/deployments","created_at":"2015-05-31T18:27:42Z","updated_at":"2016-03-29T23:47:39Z","pushed_at":"2016-03-31T08:59:25Z","git_url":"git://github.com/doomspork/elixir-school.git","ssh_url":"git@github.com:doomspork/elixir-school.git","clone_url":"https://github.com/doomspork/elixir-school.git","svn_url":"https://github.com/doomspork/elixir-school","homepage":"https://elixirschool.com","size":911,"stargazers_count":343,"watchers_count":343,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":98,"mirror_url":null,"open_issues_count":44,"forks":98,"open_issues":44,"watchers":343,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/244"},"html":{"href":"https://github.com/doomspork/elixir-school/pull/244"},"issue":{"href":"https://api.github.com/repos/doomspork/elixir-school/issues/244"},"comments":{"href":"https://api.github.com/repos/doomspork/elixir-school/issues/244/comments"},"review_comments":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/244/comments"},"review_comment":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/doomspork/elixir-school/pulls/244/commits"},"statuses":{"href":"https://api.github.com/repos/doomspork/elixir-school/statuses/4105a0b5f18b1fecbb684c7a55ee6d9ea0fb8674"}}}}