{"action":"created","comment":{"url":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments/66511680","id":66511680,"diff_hunk":"@@ -102,7 +102,13 @@ However keep in mind adding `@doc false` does not make the function private. The\n \n   * Move the undocumented function to a module with `@moduledoc false`, like `MyApp.Hidden`, ensuring the function won't be accidentally exposed or imported. Remember you can use `@moduledoc false` to hide a whole module and still document each function with `@doc`. Tools will still ignore the module.\n \n-  * Start the function name with underscores, for example, `__add__/2`, and add `@doc false`. The compiler does not import functions with leading underscores and they hint to anyone reading the code of their intended private usage.\n+  * Start the function name with one or more underscores, for example, `__add__/2`, and add `@doc false`. The compiler does not import functions with leading underscores and they hint to anyone reading the code of their intended private usage.\n+","path":"lib/elixir/pages/Writing Documentation.md","position":27,"original_position":27,"commit_id":"5ddd3e3eaff070cda26c22d1281a42fe53e4d94f","original_commit_id":"5ddd3e3eaff070cda26c22d1281a42fe53e4d94f","user":{"login":"bvosk","id":1323340,"avatar_url":"https://avatars.githubusercontent.com/u/1323340?v=3","gravatar_id":"","url":"https://api.github.com/users/bvosk","html_url":"https://github.com/bvosk","followers_url":"https://api.github.com/users/bvosk/followers","following_url":"https://api.github.com/users/bvosk/following{/other_user}","gists_url":"https://api.github.com/users/bvosk/gists{/gist_id}","starred_url":"https://api.github.com/users/bvosk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bvosk/subscriptions","organizations_url":"https://api.github.com/users/bvosk/orgs","repos_url":"https://api.github.com/users/bvosk/repos","events_url":"https://api.github.com/users/bvosk/events{/privacy}","received_events_url":"https://api.github.com/users/bvosk/received_events","type":"User","site_admin":false},"body":"I'm new and it's my first time reading through this section. These recommendations are confusing to me because they seem to suggest a coupling between documentation being generated and a function being exposed to users.\r\n\r\nAs I understand it these decisions are decoupled (and should be). Authors can use `def` vs `defp` when deciding to expose the function to users, and use `@doc` to decide if they want to document the function. For example:\r\n\r\n```elixir\r\ndefmodule MyApp.Example do\r\n  @moduledoc \"\"\"\r\n  This is an example of a module with all 4 combinations of functions.\r\n  \"\"\"\r\n\r\n  @doc \"Documentation\"\r\n  def public_documented, do: 0\r\n\r\n  @doc false\r\n  def public_undocumented, do: 0\r\n\r\n  @doc \"Documentation\"\r\n  defp private_documented, do: 0\r\n\r\n  @doc false\r\n  defp private_undocumented, do: 0\r\nend\r\n```\r\n\r\nIs that correct? If so I could take a shot at making the docs a little clearer. If I have something wrong, then I'm sorry to waste time! Like I said I'm very new at this.\r\n","created_at":"2016-06-09T20:03:25Z","updated_at":"2016-06-09T20:03:25Z","html_url":"https://github.com/elixir-lang/elixir/pull/4634#discussion_r66511680","pull_request_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634","_links":{"self":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/comments/66511680"},"html":{"href":"https://github.com/elixir-lang/elixir/pull/4634#discussion_r66511680"},"pull_request":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634"}}},"pull_request":{"url":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634","id":70233702,"html_url":"https://github.com/elixir-lang/elixir/pull/4634","diff_url":"https://github.com/elixir-lang/elixir/pull/4634.diff","patch_url":"https://github.com/elixir-lang/elixir/pull/4634.patch","issue_url":"https://api.github.com/repos/elixir-lang/elixir/issues/4634","number":4634,"state":"closed","locked":false,"title":"Rewords the section about hiding docs in \"Writing Documentation\"","user":{"login":"fxn","id":3387,"avatar_url":"https://avatars.githubusercontent.com/u/3387?v=3","gravatar_id":"","url":"https://api.github.com/users/fxn","html_url":"https://github.com/fxn","followers_url":"https://api.github.com/users/fxn/followers","following_url":"https://api.github.com/users/fxn/following{/other_user}","gists_url":"https://api.github.com/users/fxn/gists{/gist_id}","starred_url":"https://api.github.com/users/fxn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fxn/subscriptions","organizations_url":"https://api.github.com/users/fxn/orgs","repos_url":"https://api.github.com/users/fxn/repos","events_url":"https://api.github.com/users/fxn/events{/privacy}","received_events_url":"https://api.github.com/users/fxn/received_events","type":"User","site_admin":false},"body":"This PR proposes a revision of the \"Privacy\" section in \"Writing Documentation\".\r\n\r\nThe current \"Privacy\" section starts saying things about private functions, that they cannot be documented, etc., and then starts explaining a few techniques.\r\n\r\nBut I think that's not really the point of this section. This section is really about hiding documentation for modules and public functions that do not belong to the public interface for end users.\r\n\r\nThis proposal then splits this in two sections: The first one is similar to the original and introduces the common use case for hiding documentation which is having two levels of (technically) public interface.\r\n\r\nThen a new section explains how private functions are conventionally documented in Elixir.","created_at":"2016-05-16T17:53:08Z","updated_at":"2016-06-09T20:03:25Z","closed_at":"2016-05-17T13:16:35Z","merged_at":"2016-05-17T13:16:35Z","merge_commit_sha":"0bfaacfd87673878f4ddc14464b5c9196aa86899","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634/commits","review_comments_url":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634/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/4634/comments","statuses_url":"https://api.github.com/repos/elixir-lang/elixir/statuses/5ddd3e3eaff070cda26c22d1281a42fe53e4d94f","head":{"label":"fxn:master","ref":"master","sha":"5ddd3e3eaff070cda26c22d1281a42fe53e4d94f","user":{"login":"fxn","id":3387,"avatar_url":"https://avatars.githubusercontent.com/u/3387?v=3","gravatar_id":"","url":"https://api.github.com/users/fxn","html_url":"https://github.com/fxn","followers_url":"https://api.github.com/users/fxn/followers","following_url":"https://api.github.com/users/fxn/following{/other_user}","gists_url":"https://api.github.com/users/fxn/gists{/gist_id}","starred_url":"https://api.github.com/users/fxn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fxn/subscriptions","organizations_url":"https://api.github.com/users/fxn/orgs","repos_url":"https://api.github.com/users/fxn/repos","events_url":"https://api.github.com/users/fxn/events{/privacy}","received_events_url":"https://api.github.com/users/fxn/received_events","type":"User","site_admin":false},"repo":{"id":58948652,"name":"elixir","full_name":"fxn/elixir","owner":{"login":"fxn","id":3387,"avatar_url":"https://avatars.githubusercontent.com/u/3387?v=3","gravatar_id":"","url":"https://api.github.com/users/fxn","html_url":"https://github.com/fxn","followers_url":"https://api.github.com/users/fxn/followers","following_url":"https://api.github.com/users/fxn/following{/other_user}","gists_url":"https://api.github.com/users/fxn/gists{/gist_id}","starred_url":"https://api.github.com/users/fxn/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/fxn/subscriptions","organizations_url":"https://api.github.com/users/fxn/orgs","repos_url":"https://api.github.com/users/fxn/repos","events_url":"https://api.github.com/users/fxn/events{/privacy}","received_events_url":"https://api.github.com/users/fxn/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/fxn/elixir","description":"Elixir is a dynamic, functional language designed for building scalable and maintainable applications","fork":true,"url":"https://api.github.com/repos/fxn/elixir","forks_url":"https://api.github.com/repos/fxn/elixir/forks","keys_url":"https://api.github.com/repos/fxn/elixir/keys{/key_id}","collaborators_url":"https://api.github.com/repos/fxn/elixir/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/fxn/elixir/teams","hooks_url":"https://api.github.com/repos/fxn/elixir/hooks","issue_events_url":"https://api.github.com/repos/fxn/elixir/issues/events{/number}","events_url":"https://api.github.com/repos/fxn/elixir/events","assignees_url":"https://api.github.com/repos/fxn/elixir/assignees{/user}","branches_url":"https://api.github.com/repos/fxn/elixir/branches{/branch}","tags_url":"https://api.github.com/repos/fxn/elixir/tags","blobs_url":"https://api.github.com/repos/fxn/elixir/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/fxn/elixir/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/fxn/elixir/git/refs{/sha}","trees_url":"https://api.github.com/repos/fxn/elixir/git/trees{/sha}","statuses_url":"https://api.github.com/repos/fxn/elixir/statuses/{sha}","languages_url":"https://api.github.com/repos/fxn/elixir/languages","stargazers_url":"https://api.github.com/repos/fxn/elixir/stargazers","contributors_url":"https://api.github.com/repos/fxn/elixir/contributors","subscribers_url":"https://api.github.com/repos/fxn/elixir/subscribers","subscription_url":"https://api.github.com/repos/fxn/elixir/subscription","commits_url":"https://api.github.com/repos/fxn/elixir/commits{/sha}","git_commits_url":"https://api.github.com/repos/fxn/elixir/git/commits{/sha}","comments_url":"https://api.github.com/repos/fxn/elixir/comments{/number}","issue_comment_url":"https://api.github.com/repos/fxn/elixir/issues/comments{/number}","contents_url":"https://api.github.com/repos/fxn/elixir/contents/{+path}","compare_url":"https://api.github.com/repos/fxn/elixir/compare/{base}...{head}","merges_url":"https://api.github.com/repos/fxn/elixir/merges","archive_url":"https://api.github.com/repos/fxn/elixir/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/fxn/elixir/downloads","issues_url":"https://api.github.com/repos/fxn/elixir/issues{/number}","pulls_url":"https://api.github.com/repos/fxn/elixir/pulls{/number}","milestones_url":"https://api.github.com/repos/fxn/elixir/milestones{/number}","notifications_url":"https://api.github.com/repos/fxn/elixir/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/fxn/elixir/labels{/name}","releases_url":"https://api.github.com/repos/fxn/elixir/releases{/id}","deployments_url":"https://api.github.com/repos/fxn/elixir/deployments","created_at":"2016-05-16T16:32:21Z","updated_at":"2016-05-16T16:32:24Z","pushed_at":"2016-05-23T19:27:59Z","git_url":"git://github.com/fxn/elixir.git","ssh_url":"git@github.com:fxn/elixir.git","clone_url":"https://github.com/fxn/elixir.git","svn_url":"https://github.com/fxn/elixir","homepage":"http://elixir-lang.org/","size":35207,"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":"394fcb7dfd73b39448e8e0faa124db7cc43bf4a0","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-06-09T18:29:59Z","pushed_at":"2016-06-09T18:40:11Z","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":42978,"stargazers_count":7228,"watchers_count":7228,"language":"Elixir","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":998,"mirror_url":null,"open_issues_count":16,"forks":998,"open_issues":16,"watchers":7228,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634"},"html":{"href":"https://github.com/elixir-lang/elixir/pull/4634"},"issue":{"href":"https://api.github.com/repos/elixir-lang/elixir/issues/4634"},"comments":{"href":"https://api.github.com/repos/elixir-lang/elixir/issues/4634/comments"},"review_comments":{"href":"https://api.github.com/repos/elixir-lang/elixir/pulls/4634/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/4634/commits"},"statuses":{"href":"https://api.github.com/repos/elixir-lang/elixir/statuses/5ddd3e3eaff070cda26c22d1281a42fe53e4d94f"}}}}
{"actor":{"display_login":"bvosk"}}