{"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/22899875","id":22899875,"diff_hunk":"@@ -0,0 +1,125 @@\n+- Start Date: 2014-12-08\n+- RFC PR: (leave this empty)\n+- Rust Issue: (leave this empty)\n+\n+# Summary\n+\n+This is a conventions RFC, providing guidance on providing API documentation\n+for Rust projects, including the Rust language itself.\n+\n+# Motivation\n+\n+Documentation is an extremely important part of any project. It's important\n+that we have consistency in our documentation.\n+\n+For the most part, the RFC proposes guidelines that are already followed today,\n+but it tries to motivate and clarify them.\n+\n+# Detailed design\n+\n+There are a number of indivudal guidelines:\n+\n+## Use line comments\n+\n+Avoid block comments. Use line comments instead:\n+\n+```rust\n+// Wait for the main task to return, and set the process error code\n+// appropriately.\n+```\n+\n+Instead of:\n+\n+```rust\n+/*\n+ * Wait for the main task to return, and set the process error code\n+ * appropriately.\n+ */\n+```\n+\n+Only use inner doc comments //! to write crate and module-level documentation, nothing else.\n+\n+## Formatting\n+\n+The first line in any doc comment should be a single-line short sentence\n+providing a summary of the code. This line is used as a summary description\n+throughout Rustdoc's output, so it's a good idea to keep it short.\n+\n+All doc comments, including the summary line, should begin with a capital\n+letter and end with a period, question mark, or exclamation point. Prefer full\n+sentences to fragments.\n+\n+The summary line should be written in third person singular present indicative\n+form. Basically, this means write \"Returns\" instead of \"Return\".\n+\n+## Using Markdown\n+\n+Within doc comments, use Markdown to format your documentation.\n+\n+Use top level headings # to indicate sections within your comment. Common headings:\n+\n+* Examples\n+* Panics\n+* Failure\n+\n+Even if you only include one example, use the plural form: \"Examples\" rather\n+than \"Example\". Future tooling is easier this way.\n+\n+Use graves (`) to denote a code fragment within a sentence.\n+\n+Use triple graves (```) to write longer examples, like this:\n+\n+    This code does something cool.\n+\n+    ```rust\n+    let x = foo();\n+    x.bar();\n+    ```\n+\n+When appropriate, make use of Rustdoc's modifiers. Annotate triple grave blocks with\n+the appropriate formatting directive. While they default to Rust in Rustdoc, prefer\n+being explicit, so that it highlights syntax in places that do not, like GitHub.\n+\n+    ```rust\n+    println!(\"Hello, world!\");\n+    ```\n+\n+    ```ruby\n+    puts \"Hello\"\n+    ```\n+\n+Rustdoc is able to test all Rust examples embedded inside of documentation, so\n+it's important to mark what is not Rust so your tests don't fail.\n+\n+References and citation should be linked inline. Prefer","path":"text/0000-api-comment-conventions.md","position":94,"original_position":94,"commit_id":"40d369ac6a5ace63d00acbeafddf61f18e046cac","original_commit_id":"40d369ac6a5ace63d00acbeafddf61f18e046cac","user":{"login":"nick29581","id":762626,"avatar_url":"https://avatars.githubusercontent.com/u/762626?v=3","gravatar_id":"","url":"https://api.github.com/users/nick29581","html_url":"https://github.com/nick29581","followers_url":"https://api.github.com/users/nick29581/followers","following_url":"https://api.github.com/users/nick29581/following{/other_user}","gists_url":"https://api.github.com/users/nick29581/gists{/gist_id}","starred_url":"https://api.github.com/users/nick29581/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nick29581/subscriptions","organizations_url":"https://api.github.com/users/nick29581/orgs","repos_url":"https://api.github.com/users/nick29581/repos","events_url":"https://api.github.com/users/nick29581/events{/privacy}","received_events_url":"https://api.github.com/users/nick29581/received_events","type":"User","site_admin":false},"body":"As long as you have the title, authors, and year, any format is OK, but having those things is standard academically and makes things easy to find.","created_at":"2015-01-13T22:13:36Z","updated_at":"2015-01-13T22:13:36Z","html_url":"https://github.com/rust-lang/rfcs/pull/505#discussion_r22899875","pull_request_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/505","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/22899875"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/505#discussion_r22899875"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/505"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/505","id":25685116,"html_url":"https://github.com/rust-lang/rfcs/pull/505","diff_url":"https://github.com/rust-lang/rfcs/pull/505.diff","patch_url":"https://github.com/rust-lang/rfcs/pull/505.patch","issue_url":"https://api.github.com/repos/rust-lang/rfcs/issues/505","number":505,"state":"open","locked":false,"title":"API comment conventions","user":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"body":"[Rendered](https://github.com/steveklabnik/rfcs/blob/api_comment_conventions/text/0000-api-comment-conventions.md)\r\n\r\nI'm mostly trying to codify what we already have consensus on, rather than address every possible question. I can forsee this kind of RFC getting very bogged down in a number of different details, and we can always add more things in a future RFC.","created_at":"2014-12-08T18:14:20Z","updated_at":"2015-01-13T22:13:37Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c8a7a11f8535d7afca29026e655e21581df4f3c1","assignee":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/505/commits","review_comments_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/505/comments","review_comment_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/{number}","comments_url":"https://api.github.com/repos/rust-lang/rfcs/issues/505/comments","statuses_url":"https://api.github.com/repos/rust-lang/rfcs/statuses/40d369ac6a5ace63d00acbeafddf61f18e046cac","head":{"label":"steveklabnik:api_comment_conventions","ref":"api_comment_conventions","sha":"40d369ac6a5ace63d00acbeafddf61f18e046cac","user":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"repo":{"id":20783435,"name":"rfcs","full_name":"steveklabnik/rfcs","owner":{"login":"steveklabnik","id":27786,"avatar_url":"https://avatars.githubusercontent.com/u/27786?v=3","gravatar_id":"","url":"https://api.github.com/users/steveklabnik","html_url":"https://github.com/steveklabnik","followers_url":"https://api.github.com/users/steveklabnik/followers","following_url":"https://api.github.com/users/steveklabnik/following{/other_user}","gists_url":"https://api.github.com/users/steveklabnik/gists{/gist_id}","starred_url":"https://api.github.com/users/steveklabnik/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/steveklabnik/subscriptions","organizations_url":"https://api.github.com/users/steveklabnik/orgs","repos_url":"https://api.github.com/users/steveklabnik/repos","events_url":"https://api.github.com/users/steveklabnik/events{/privacy}","received_events_url":"https://api.github.com/users/steveklabnik/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/steveklabnik/rfcs","description":"RFCs for changes to Rust","fork":true,"url":"https://api.github.com/repos/steveklabnik/rfcs","forks_url":"https://api.github.com/repos/steveklabnik/rfcs/forks","keys_url":"https://api.github.com/repos/steveklabnik/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/steveklabnik/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/steveklabnik/rfcs/teams","hooks_url":"https://api.github.com/repos/steveklabnik/rfcs/hooks","issue_events_url":"https://api.github.com/repos/steveklabnik/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/steveklabnik/rfcs/events","assignees_url":"https://api.github.com/repos/steveklabnik/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/steveklabnik/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/steveklabnik/rfcs/tags","blobs_url":"https://api.github.com/repos/steveklabnik/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/steveklabnik/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/steveklabnik/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/steveklabnik/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/steveklabnik/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/steveklabnik/rfcs/languages","stargazers_url":"https://api.github.com/repos/steveklabnik/rfcs/stargazers","contributors_url":"https://api.github.com/repos/steveklabnik/rfcs/contributors","subscribers_url":"https://api.github.com/repos/steveklabnik/rfcs/subscribers","subscription_url":"https://api.github.com/repos/steveklabnik/rfcs/subscription","commits_url":"https://api.github.com/repos/steveklabnik/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/steveklabnik/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/steveklabnik/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/steveklabnik/rfcs/issues/comments/{number}","contents_url":"https://api.github.com/repos/steveklabnik/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/steveklabnik/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/steveklabnik/rfcs/merges","archive_url":"https://api.github.com/repos/steveklabnik/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/steveklabnik/rfcs/downloads","issues_url":"https://api.github.com/repos/steveklabnik/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/steveklabnik/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/steveklabnik/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/steveklabnik/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/steveklabnik/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/steveklabnik/rfcs/releases{/id}","created_at":"2014-06-12T21:25:46Z","updated_at":"2014-12-22T18:25:17Z","pushed_at":"2014-12-22T18:25:17Z","git_url":"git://github.com/steveklabnik/rfcs.git","ssh_url":"git@github.com:steveklabnik/rfcs.git","clone_url":"https://github.com/steveklabnik/rfcs.git","svn_url":"https://github.com/steveklabnik/rfcs","homepage":"","size":1033,"stargazers_count":0,"watchers_count":0,"language":null,"has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"base":{"label":"rust-lang:master","ref":"master","sha":"44e304335c1817c65a0c84284ef3691bd8f586d1","user":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"repo":{"id":17527989,"name":"rfcs","full_name":"rust-lang/rfcs","owner":{"login":"rust-lang","id":5430905,"avatar_url":"https://avatars.githubusercontent.com/u/5430905?v=3","gravatar_id":"","url":"https://api.github.com/users/rust-lang","html_url":"https://github.com/rust-lang","followers_url":"https://api.github.com/users/rust-lang/followers","following_url":"https://api.github.com/users/rust-lang/following{/other_user}","gists_url":"https://api.github.com/users/rust-lang/gists{/gist_id}","starred_url":"https://api.github.com/users/rust-lang/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rust-lang/subscriptions","organizations_url":"https://api.github.com/users/rust-lang/orgs","repos_url":"https://api.github.com/users/rust-lang/repos","events_url":"https://api.github.com/users/rust-lang/events{/privacy}","received_events_url":"https://api.github.com/users/rust-lang/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rust-lang/rfcs","description":"RFCs for changes to Rust","fork":false,"url":"https://api.github.com/repos/rust-lang/rfcs","forks_url":"https://api.github.com/repos/rust-lang/rfcs/forks","keys_url":"https://api.github.com/repos/rust-lang/rfcs/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rust-lang/rfcs/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rust-lang/rfcs/teams","hooks_url":"https://api.github.com/repos/rust-lang/rfcs/hooks","issue_events_url":"https://api.github.com/repos/rust-lang/rfcs/issues/events{/number}","events_url":"https://api.github.com/repos/rust-lang/rfcs/events","assignees_url":"https://api.github.com/repos/rust-lang/rfcs/assignees{/user}","branches_url":"https://api.github.com/repos/rust-lang/rfcs/branches{/branch}","tags_url":"https://api.github.com/repos/rust-lang/rfcs/tags","blobs_url":"https://api.github.com/repos/rust-lang/rfcs/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rust-lang/rfcs/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rust-lang/rfcs/git/refs{/sha}","trees_url":"https://api.github.com/repos/rust-lang/rfcs/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rust-lang/rfcs/statuses/{sha}","languages_url":"https://api.github.com/repos/rust-lang/rfcs/languages","stargazers_url":"https://api.github.com/repos/rust-lang/rfcs/stargazers","contributors_url":"https://api.github.com/repos/rust-lang/rfcs/contributors","subscribers_url":"https://api.github.com/repos/rust-lang/rfcs/subscribers","subscription_url":"https://api.github.com/repos/rust-lang/rfcs/subscription","commits_url":"https://api.github.com/repos/rust-lang/rfcs/commits{/sha}","git_commits_url":"https://api.github.com/repos/rust-lang/rfcs/git/commits{/sha}","comments_url":"https://api.github.com/repos/rust-lang/rfcs/comments{/number}","issue_comment_url":"https://api.github.com/repos/rust-lang/rfcs/issues/comments/{number}","contents_url":"https://api.github.com/repos/rust-lang/rfcs/contents/{+path}","compare_url":"https://api.github.com/repos/rust-lang/rfcs/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rust-lang/rfcs/merges","archive_url":"https://api.github.com/repos/rust-lang/rfcs/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rust-lang/rfcs/downloads","issues_url":"https://api.github.com/repos/rust-lang/rfcs/issues{/number}","pulls_url":"https://api.github.com/repos/rust-lang/rfcs/pulls{/number}","milestones_url":"https://api.github.com/repos/rust-lang/rfcs/milestones{/number}","notifications_url":"https://api.github.com/repos/rust-lang/rfcs/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rust-lang/rfcs/labels{/name}","releases_url":"https://api.github.com/repos/rust-lang/rfcs/releases{/id}","created_at":"2014-03-07T21:29:00Z","updated_at":"2015-01-13T11:38:10Z","pushed_at":"2015-01-13T00:31:18Z","git_url":"git://github.com/rust-lang/rfcs.git","ssh_url":"git@github.com:rust-lang/rfcs.git","clone_url":"https://github.com/rust-lang/rfcs.git","svn_url":"https://github.com/rust-lang/rfcs","homepage":"","size":6228,"stargazers_count":222,"watchers_count":222,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":140,"mirror_url":null,"open_issues_count":218,"forks":140,"open_issues":218,"watchers":222,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/505"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/505"},"issue":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/505"},"comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/505/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/505/comments"},"review_comment":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/{number}"},"commits":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/505/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/rfcs/statuses/40d369ac6a5ace63d00acbeafddf61f18e046cac"}}}}