{"action":"created","comment":{"url":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments/77138171","id":77138171,"diff_hunk":"@@ -53,33 +53,41 @@ The compiler will infer this argument as `map`. Sometimes the inference will be\n \n ## Recommendations\n \n-There are a couple tips we recommend developers to follow when writing documentation:\n+When writing documentation:\n \n-  * Keep the first paragraph of the documentation concise and simple, typically one-line. Tools like [ExDoc](https://github.com/elixir-lang/ex_doc/) use the first line to generate a summary.\n+  * Keep the first paragraph of the documentation concise, typically one-line. Tools like [ExDoc](https://github.com/elixir-lang/ex_doc/) use the first line to generate a summary.\n \n-  * Markdown uses backticks (`` ` ``) to quote code. Elixir builds on top of that to automatically generate links when module or function names are referenced. For this reason, always use full module names. If you have a module called `MyApp.Hello`, always reference it as `` `MyApp.Hello` `` and never as `` `Hello` ``. Function names must be referenced by name and arity if they are local, as in `` `world/1` ``, or by module, name and arity if pointing to an external module: `` `MyApp.Hello.world/1` ``. Referencing a `@callback` can be done by prepending `c:`, as in `` `c:world/1` ``; and a `@type` by using `t:`, as in `t:values/0`.\n+  * Reference modules by their full name.\n \n-  * When the documentation has multiple sections, always start the section heading by using `##`. The first heading is reserved for modules and function names.\n+  Markdown uses backticks (`` ` ``) to quote code. Elixir builds on top of that to automatically generate links when module or function names are referenced. For this reason, always use full module names. If you have a module called `MyApp.Hello`, always reference it as `` `MyApp.Hello` `` and never as `` `Hello` ``.\n \n-  * When documenting a function with multiple clauses, the documentation must be placed before the first clause. Documentation is always per function and arity and not per clause.\n+  * Reference functions by name and arity if they are local, as in `` `world/1` ``, or by module, name and arity if pointing to an external module: `` `MyApp.Hello.world/1` ``.\n+\n+  * Reference a `@callback` by prepending `c:`, as in `` `c:world/1` ``.\n+\n+  * Reference a `@type` by prepending `t:`, as in `` `t:values/0` ``.\n+\n+  * Start new sections with second level markdown headings `##`. The first heading is reserved for module and function names.\n+\n+  * Place documentation before the first clause of multi-clause functions. Documentation is always per function and arity and not per clause.\n \n ## Doctests\n \n-We recommend developers to include examples in their documentation, often under its own `## Examples` heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation. Doctests work by parsing out code samples starting with `iex>` from the documentation. You can read more about it at `ExUnit.DocTest`.\n+We recommend developers include examples in their documentation, often under their own `## Examples` heading. To ensure examples do not get out of date, Elixir's test framework (ExUnit) provides a feature called doctests that allows developers to test the examples in their documentation. Doctests work by parsing out code samples starting with `iex>` from the documentation. You can read more about it at `ExUnit.DocTest`.","path":"lib/elixir/pages/Writing Documentation.md","position":30,"original_position":30,"commit_id":"e3fcae97dc39c5869fc42a602ba0e4106911961a","original_commit_id":"e3fcae97dc39c5869fc42a602ba0e4106911961a","user":{"login":"whatyouhide","id":3890250,"avatar_url":"https://avatars.githubusercontent.com/u/3890250?v=3","gravatar_id":"","url":"https://api.github.com/users/whatyouhide","html_url":"https://github.com/whatyouhide","followers_url":"https://api.github.com/users/whatyouhide/followers","following_url":"https://api.github.com/users/whatyouhide/following{/other_user}","gists_url":"https://api.github.com/users/whatyouhide/gists{/gist_id}","starred_url":"https://api.github.com/users/whatyouhide/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/whatyouhide/subscriptions","organizations_url":"https://api.github.com/users/whatyouhide/orgs","repos_url":"https://api.github.com/users/whatyouhide/repos","events_url":"https://api.github.com/users/whatyouhide/events{/privacy}","received_events_url":"https://api.github.com/users/whatyouhide/received_events","type":"User","site_admin":false},"body":"\"recommend developers include\" is correct over \"recomment developers to include\", but maybe \"We recommend *that* developers include\" reads even nicer?","created_at":"2016-09-01T09:03:19Z","updated_at":"2016-09-01T09:03:19Z","html_url":"https://github.com/elixir-lang/elixir/pull/5180#discussion_r77138171","pull_request_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180","_links":{"self":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments/77138171"},"html":{"href":"https://github.com/elixir-lang/elixir/pull/5180#discussion_r77138171"},"pull_request":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180"}}},"pull_request":{"url":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180","id":83549695,"html_url":"https://github.com/elixir-lang/elixir/pull/5180","diff_url":"https://github.com/elixir-lang/elixir/pull/5180.diff","patch_url":"https://github.com/elixir-lang/elixir/pull/5180.patch","issue_url":"https://api.github.com/repos/elixir-lang/elixir/issues/5180","number":5180,"state":"open","locked":false,"title":"Minor grammatical improvements to documentation writing guide","user":{"login":"gabrieltaylor","id":3871682,"avatar_url":"https://avatars.githubusercontent.com/u/3871682?v=3","gravatar_id":"","url":"https://api.github.com/users/gabrieltaylor","html_url":"https://github.com/gabrieltaylor","followers_url":"https://api.github.com/users/gabrieltaylor/followers","following_url":"https://api.github.com/users/gabrieltaylor/following{/other_user}","gists_url":"https://api.github.com/users/gabrieltaylor/gists{/gist_id}","starred_url":"https://api.github.com/users/gabrieltaylor/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gabrieltaylor/subscriptions","organizations_url":"https://api.github.com/users/gabrieltaylor/orgs","repos_url":"https://api.github.com/users/gabrieltaylor/repos","events_url":"https://api.github.com/users/gabrieltaylor/events{/privacy}","received_events_url":"https://api.github.com/users/gabrieltaylor/received_events","type":"User","site_admin":false},"body":"","created_at":"2016-08-31T23:55:16Z","updated_at":"2016-09-01T09:03:19Z","closed_at":null,"merged_at":null,"merge_commit_sha":"02c623918df2110c6d8e5882ad9330e9f065d2b5","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180/commits","review_comments_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180/comments","review_comment_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments{/number}","comments_url":"https://api.github.com/repos/elixir-lang/elixir/issues/5180/comments","statuses_url":"https://api.github.com/repos/elixir-lang/elixir/statuses/e3fcae97dc39c5869fc42a602ba0e4106911961a","head":{"label":"gabrieltaylor:gtr/update_writing_documentation","ref":"gtr/update_writing_documentation","sha":"e3fcae97dc39c5869fc42a602ba0e4106911961a","user":{"login":"gabrieltaylor","id":3871682,"avatar_url":"https://avatars.githubusercontent.com/u/3871682?v=3","gravatar_id":"","url":"https://api.github.com/users/gabrieltaylor","html_url":"https://github.com/gabrieltaylor","followers_url":"https://api.github.com/users/gabrieltaylor/followers","following_url":"https://api.github.com/users/gabrieltaylor/following{/other_user}","gists_url":"https://api.github.com/users/gabrieltaylor/gists{/gist_id}","starred_url":"https://api.github.com/users/gabrieltaylor/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gabrieltaylor/subscriptions","organizations_url":"https://api.github.com/users/gabrieltaylor/orgs","repos_url":"https://api.github.com/users/gabrieltaylor/repos","events_url":"https://api.github.com/users/gabrieltaylor/events{/privacy}","received_events_url":"https://api.github.com/users/gabrieltaylor/received_events","type":"User","site_admin":false},"repo":{"id":37797168,"name":"elixir","full_name":"gabrieltaylor/elixir","owner":{"login":"gabrieltaylor","id":3871682,"avatar_url":"https://avatars.githubusercontent.com/u/3871682?v=3","gravatar_id":"","url":"https://api.github.com/users/gabrieltaylor","html_url":"https://github.com/gabrieltaylor","followers_url":"https://api.github.com/users/gabrieltaylor/followers","following_url":"https://api.github.com/users/gabrieltaylor/following{/other_user}","gists_url":"https://api.github.com/users/gabrieltaylor/gists{/gist_id}","starred_url":"https://api.github.com/users/gabrieltaylor/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gabrieltaylor/subscriptions","organizations_url":"https://api.github.com/users/gabrieltaylor/orgs","repos_url":"https://api.github.com/users/gabrieltaylor/repos","events_url":"https://api.github.com/users/gabrieltaylor/events{/privacy}","received_events_url":"https://api.github.com/users/gabrieltaylor/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/gabrieltaylor/elixir","description":"Elixir is a dynamic, functional language designed for building scalable and maintainable applications","fork":true,"url":"https://api.github.com/repos/gabrieltaylor/elixir","forks_url":"https://api.github.com/repos/gabrieltaylor/elixir/forks","keys_url":"https://api.github.com/repos/gabrieltaylor/elixir/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gabrieltaylor/elixir/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gabrieltaylor/elixir/teams","hooks_url":"https://api.github.com/repos/gabrieltaylor/elixir/hooks","issue_events_url":"https://api.github.com/repos/gabrieltaylor/elixir/issues/events{/number}","events_url":"https://api.github.com/repos/gabrieltaylor/elixir/events","assignees_url":"https://api.github.com/repos/gabrieltaylor/elixir/assignees{/user}","branches_url":"https://api.github.com/repos/gabrieltaylor/elixir/branches{/branch}","tags_url":"https://api.github.com/repos/gabrieltaylor/elixir/tags","blobs_url":"https://api.github.com/repos/gabrieltaylor/elixir/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gabrieltaylor/elixir/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gabrieltaylor/elixir/git/refs{/sha}","trees_url":"https://api.github.com/repos/gabrieltaylor/elixir/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gabrieltaylor/elixir/statuses/{sha}","languages_url":"https://api.github.com/repos/gabrieltaylor/elixir/languages","stargazers_url":"https://api.github.com/repos/gabrieltaylor/elixir/stargazers","contributors_url":"https://api.github.com/repos/gabrieltaylor/elixir/contributors","subscribers_url":"https://api.github.com/repos/gabrieltaylor/elixir/subscribers","subscription_url":"https://api.github.com/repos/gabrieltaylor/elixir/subscription","commits_url":"https://api.github.com/repos/gabrieltaylor/elixir/commits{/sha}","git_commits_url":"https://api.github.com/repos/gabrieltaylor/elixir/git/commits{/sha}","comments_url":"https://api.github.com/repos/gabrieltaylor/elixir/comments{/number}","issue_comment_url":"https://api.github.com/repos/gabrieltaylor/elixir/issues/comments{/number}","contents_url":"https://api.github.com/repos/gabrieltaylor/elixir/contents/{+path}","compare_url":"https://api.github.com/repos/gabrieltaylor/elixir/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gabrieltaylor/elixir/merges","archive_url":"https://api.github.com/repos/gabrieltaylor/elixir/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gabrieltaylor/elixir/downloads","issues_url":"https://api.github.com/repos/gabrieltaylor/elixir/issues{/number}","pulls_url":"https://api.github.com/repos/gabrieltaylor/elixir/pulls{/number}","milestones_url":"https://api.github.com/repos/gabrieltaylor/elixir/milestones{/number}","notifications_url":"https://api.github.com/repos/gabrieltaylor/elixir/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gabrieltaylor/elixir/labels{/name}","releases_url":"https://api.github.com/repos/gabrieltaylor/elixir/releases{/id}","deployments_url":"https://api.github.com/repos/gabrieltaylor/elixir/deployments","created_at":"2015-06-21T04:58:08Z","updated_at":"2015-06-21T04:58:10Z","pushed_at":"2016-08-31T23:53:31Z","git_url":"git://github.com/gabrieltaylor/elixir.git","ssh_url":"git@github.com:gabrieltaylor/elixir.git","clone_url":"https://github.com/gabrieltaylor/elixir.git","svn_url":"https://github.com/gabrieltaylor/elixir","homepage":"http://elixir-lang.org/","size":28998,"stargazers_count":0,"watchers_count":0,"language":"Elixir","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":"elixir-lang:master","ref":"master","sha":"f2416a323d5aed6063ae6c26980427e78f6b910e","user":{"login":"elixir-lang","id":1481354,"avatar_url":"https://avatars.githubusercontent.com/u/1481354?v=3","gravatar_id":"","url":"https://api.github.com/users/elixir-lang","html_url":"https://github.com/elixir-lang","followers_url":"https://api.github.com/users/elixir-lang/followers","following_url":"https://api.github.com/users/elixir-lang/following{/other_user}","gists_url":"https://api.github.com/users/elixir-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/elixir-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/elixir-lang/subscriptions","organizations_url":"https://api.github.com/users/elixir-lang/orgs","repos_url":"https://api.github.com/users/elixir-lang/repos","events_url":"https://api.github.com/users/elixir-lang/events{/privacy}","received_events_url":"https://api.github.com/users/elixir-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":1234714,"name":"elixir","full_name":"elixir-lang/elixir","owner":{"login":"elixir-lang","id":1481354,"avatar_url":"https://avatars.githubusercontent.com/u/1481354?v=3","gravatar_id":"","url":"https://api.github.com/users/elixir-lang","html_url":"https://github.com/elixir-lang","followers_url":"https://api.github.com/users/elixir-lang/followers","following_url":"https://api.github.com/users/elixir-lang/following{/other_user}","gists_url":"https://api.github.com/users/elixir-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/elixir-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/elixir-lang/subscriptions","organizations_url":"https://api.github.com/users/elixir-lang/orgs","repos_url":"https://api.github.com/users/elixir-lang/repos","events_url":"https://api.github.com/users/elixir-lang/events{/privacy}","received_events_url":"https://api.github.com/users/elixir-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/elixir-lang/elixir","description":"Elixir is a dynamic, functional language designed for building scalable and maintainable applications","fork":false,"url":"https://api.github.com/repos/elixir-lang/elixir","forks_url":"https://api.github.com/repos/elixir-lang/elixir/forks","keys_url":"https://api.github.com/repos/elixir-lang/elixir/keys{/key_id}","collaborators_url":"https://api.github.com/repos/elixir-lang/elixir/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/elixir-lang/elixir/teams","hooks_url":"https://api.github.com/repos/elixir-lang/elixir/hooks","issue_events_url":"https://api.github.com/repos/elixir-lang/elixir/issues/events{/number}","events_url":"https://api.github.com/repos/elixir-lang/elixir/events","assignees_url":"https://api.github.com/repos/elixir-lang/elixir/assignees{/user}","branches_url":"https://api.github.com/repos/elixir-lang/elixir/branches{/branch}","tags_url":"https://api.github.com/repos/elixir-lang/elixir/tags","blobs_url":"https://api.github.com/repos/elixir-lang/elixir/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/elixir-lang/elixir/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/elixir-lang/elixir/git/refs{/sha}","trees_url":"https://api.github.com/repos/elixir-lang/elixir/git/trees{/sha}","statuses_url":"https://api.github.com/repos/elixir-lang/elixir/statuses/{sha}","languages_url":"https://api.github.com/repos/elixir-lang/elixir/languages","stargazers_url":"https://api.github.com/repos/elixir-lang/elixir/stargazers","contributors_url":"https://api.github.com/repos/elixir-lang/elixir/contributors","subscribers_url":"https://api.github.com/repos/elixir-lang/elixir/subscribers","subscription_url":"https://api.github.com/repos/elixir-lang/elixir/subscription","commits_url":"https://api.github.com/repos/elixir-lang/elixir/commits{/sha}","git_commits_url":"https://api.github.com/repos/elixir-lang/elixir/git/commits{/sha}","comments_url":"https://api.github.com/repos/elixir-lang/elixir/comments{/number}","issue_comment_url":"https://api.github.com/repos/elixir-lang/elixir/issues/comments{/number}","contents_url":"https://api.github.com/repos/elixir-lang/elixir/contents/{+path}","compare_url":"https://api.github.com/repos/elixir-lang/elixir/compare/{base}...{head}","merges_url":"https://api.github.com/repos/elixir-lang/elixir/merges","archive_url":"https://api.github.com/repos/elixir-lang/elixir/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/elixir-lang/elixir/downloads","issues_url":"https://api.github.com/repos/elixir-lang/elixir/issues{/number}","pulls_url":"https://api.github.com/repos/elixir-lang/elixir/pulls{/number}","milestones_url":"https://api.github.com/repos/elixir-lang/elixir/milestones{/number}","notifications_url":"https://api.github.com/repos/elixir-lang/elixir/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/elixir-lang/elixir/labels{/name}","releases_url":"https://api.github.com/repos/elixir-lang/elixir/releases{/id}","deployments_url":"https://api.github.com/repos/elixir-lang/elixir/deployments","created_at":"2011-01-09T08:43:57Z","updated_at":"2016-09-01T08:06:33Z","pushed_at":"2016-08-31T23:55:16Z","git_url":"git://github.com/elixir-lang/elixir.git","ssh_url":"git@github.com:elixir-lang/elixir.git","clone_url":"https://github.com/elixir-lang/elixir.git","svn_url":"https://github.com/elixir-lang/elixir","homepage":"http://elixir-lang.org/","size":38961,"stargazers_count":7991,"watchers_count":7991,"language":"Elixir","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":1089,"mirror_url":null,"open_issues_count":26,"forks":1089,"open_issues":26,"watchers":7991,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180"},"html":{"href":"https://github.com/elixir-lang/elixir/pull/5180"},"issue":{"href":"https://api.github.com/repos/elixir-lang/elixir/issues/5180"},"comments":{"href":"https://api.github.com/repos/elixir-lang/elixir/issues/5180/comments"},"review_comments":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180/comments"},"review_comment":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/5180/commits"},"statuses":{"href":"https://api.github.com/repos/elixir-lang/elixir/statuses/e3fcae97dc39c5869fc42a602ba0e4106911961a"}}}}
{"actor":{"display_login":"whatyouhide"}}