{"action":"created","comment":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/59602879","id":59602879,"diff_hunk":"@@ -0,0 +1,409 @@\n+- Feature Name: More API Documentation Conventions\n+- Start Date: 2016-03-31\n+- RFC PR: (leave this empty)\n+- Rust Issue: (leave this empty)\n+\n+# Summary\n+[summary]: #summary\n+\n+[RFC 505] introduced certain conventions around documenting Rust projects. This RFC supersedes\n+that one, though it has the same aims: to describe how the Rust project should be documented,\n+and provide guidance for other Rust projects as well.\n+\n+This RFC will contain some similar text as RFC 505, so that we can have one RFC with the full\n+conventions.\n+\n+[RFC 505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md\n+\n+# Motivation\n+[motivation]: #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+[design]: #detailed-design\n+\n+This RFC is large. Here’s a table of contents:\n+\n+* [Content](#content)\n+  * [Summary sentence](#summary-sentence)\n+  * [English](#english)\n+* [Form](#form)\n+  * [Use line comments](#use-line-comments)\n+  * [Using Markdown](#using-markdown)\n+* [Example](#example)\n+\n+## Content\n+[content]: #content\n+\n+These conventions relate to the contents of the documentation, the words themselves.\n+\n+### Summary sentence\n+[summary-sentence]: #summary-sentence\n+\n+In API documentation, the first line 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+The summary line should be written in third person singular present indicative\n+form. Basically, this means write “Returns” instead of “Return.”\n+\n+### English\n+[english]: #english\n+\n+This section applies to `rustc` and the standard library.\n+\n+All documentation is standardized on American English, with regards to\n+spelling, grammar, and punctuation conventions. Language changes over time,\n+so this doesn’t mean that there is always a correct answer to every grammar\n+question, but there is often some kind of formal consensus.\n+\n+One specific rule that comes up often: when quoting something for emphasis,\n+use a single quote, and put punctuation outside the quotes, ‘this’. When\n+quoting something at length, “use double quotes and put the punctuation\n+inside of the quote.” Most documentation will end up using single quotes,\n+so if you’re not sure, just stick with them.\n+\n+## Form\n+[form]: #form\n+\n+These conventions relate to the formatting of the documentation, how they\n+appear in source code.\n+\n+### Use line comments\n+[use-line-comments]: #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,\n+nothing else. When using `mod` blocks, prefer `///` outside of the block:\n+\n+```rust\n+/// This module contains tests\n+mod test {\n+    // ...\n+}\n+```\n+\n+over\n+\n+```rust\n+mod test {\n+    //! This module contains tests\n+\n+    // ...\n+}\n+```\n+\n+### Using Markdown\n+[using-markdown]: #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+* Errors\n+* Safety\n+* Aborts\n+* Undefined Behavior\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+\n+    x.bar();\n+    ```\n+\n+When appropriate, make use of Rustdoc’s modifiers. Annotate triple grave blocks with\n+the appropriate formatting directive.\n+\n+    ```rust\n+    println!(\"Hello, world!\");\n+    ```\n+\n+    ```ruby\n+    puts \"Hello\"\n+    ```\n+\n+In API documentation, feel free to rely on the default being ‘rust’:\n+\n+    /// For example:\n+    ///\n+    /// ```\n+    /// let x = 5;\n+    /// ```\n+\n+In long-form documentation, always be explicit:\n+\n+    For example:\n+\n+    ```rust\n+    let x = 5;\n+    ```\n+\n+This will highlight syntax in places that do not default to ‘rust’, like GitHub.\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 ‘reference style.’ Prefer\n+\n+```\n+[Rust website]\n+\n+[Rust website]: http://www.rust-lang.org\n+```\n+\n+to\n+\n+```\n+[Rust website](http://www.rust-lang.org)\n+```\n+\n+### Examples in API docs\n+[examples-in-api-docs]: #examples-in-api-docs\n+\n+Everything should have examples. Here is an example of how to do examples:\n+\n+```\n+/// # Examples\n+///\n+/// Basic usage:\n+///\n+/// ```\n+/// use op;\n+///\n+/// let s = \"foo\";\n+/// let answer = op::compare(s, \"bar\");\n+/// ```\n+///\n+/// Passing a closure to compare with, rather than a string:\n+///\n+/// ```\n+/// use op;\n+///\n+/// let s = \"foo\";\n+/// let answer = op::compare(s, |a| a.chars().is_whitespace().all());\n+/// ```\n+```\n+\n+For particularly simple APIs, still say “Examples” and “Basic usage:” for\n+consistency’s sake.\n+\n+### Referring to types\n+[referring-to-types]: #referring-to-types\n+\n+When talking about a type, use its full name. In other words, if the type is generic,\n+say `Option<T>`, not `Option`. An exception to this is lengthy bounds. Write `Cow<'a, B>`\n+rather than `Cow<'a, B> where B: 'a + ToOwned + ?Sized`.\n+\n+Another possibility is to write in lower case using a more generic term. In other words,\n+‘string’ can refer to a `String` or an `&str`, and ‘an option’ can be ‘an `Option<T>`’.\n+\n+### Link all the things\n+[link-all-the-things]: #link-all-the-things\n+\n+A major drawback of Markdown is that it cannot automatically link types in API documentation.\n+Do this yourself with the reference-style syntax, for ease of reading:\n+\n+```\n+/// The [`String`] passed in lorum ipsum...\n+///\n+/// [`String`]: ../string/struct.String.html\n+```","path":"text/0000-more-api-documentation-conventions.md","position":241,"original_position":241,"commit_id":"1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06","original_commit_id":"1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06","user":{"login":"starkat99","id":8295111,"avatar_url":"https://avatars.githubusercontent.com/u/8295111?v=3","gravatar_id":"","url":"https://api.github.com/users/starkat99","html_url":"https://github.com/starkat99","followers_url":"https://api.github.com/users/starkat99/followers","following_url":"https://api.github.com/users/starkat99/following{/other_user}","gists_url":"https://api.github.com/users/starkat99/gists{/gist_id}","starred_url":"https://api.github.com/users/starkat99/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/starkat99/subscriptions","organizations_url":"https://api.github.com/users/starkat99/orgs","repos_url":"https://api.github.com/users/starkat99/repos","events_url":"https://api.github.com/users/starkat99/events{/privacy}","received_events_url":"https://api.github.com/users/starkat99/received_events","type":"User","site_admin":false},"body":"I think this should be solved in rustdoc tool rather than manually. For instance, it should be trivial in a preprocessing step, assuming there's an index of symbols, to find all `[]` links that do not have a corresponding reference link and look them up in the symbol index for the proper URL.","created_at":"2016-04-13T18:42:13Z","updated_at":"2016-04-13T18:42:13Z","html_url":"https://github.com/rust-lang/rfcs/pull/1574#discussion_r59602879","pull_request_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574","_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/comments/59602879"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/1574#discussion_r59602879"},"pull_request":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574"}}},"pull_request":{"url":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574","id":65482137,"html_url":"https://github.com/rust-lang/rfcs/pull/1574","diff_url":"https://github.com/rust-lang/rfcs/pull/1574.diff","patch_url":"https://github.com/rust-lang/rfcs/pull/1574.patch","issue_url":"https://api.github.com/repos/rust-lang/rfcs/issues/1574","number":1574,"state":"open","locked":false,"title":"More api documentation 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/more-api-conventions/text/0000-more-api-documentation-conventions.md)","created_at":"2016-04-06T15:03:49Z","updated_at":"2016-04-13T18:42:13Z","closed_at":null,"merged_at":null,"merge_commit_sha":"136d88a3cb07c2e3b2b0a0a84faa6999ce07ac48","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574/commits","review_comments_url":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574/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/1574/comments","statuses_url":"https://api.github.com/repos/rust-lang/rfcs/statuses/1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06","head":{"label":"steveklabnik:more-api-conventions","ref":"more-api-conventions","sha":"1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06","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}","deployments_url":"https://api.github.com/repos/steveklabnik/rfcs/deployments","created_at":"2014-06-12T21:25:46Z","updated_at":"2014-12-22T18:25:17Z","pushed_at":"2016-04-05T20:26:22Z","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":2729,"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":"95cb9f7f2851f5099a54965354c55ef64d9559d2","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}","deployments_url":"https://api.github.com/repos/rust-lang/rfcs/deployments","created_at":"2014-03-07T21:29:00Z","updated_at":"2016-04-13T02:32:53Z","pushed_at":"2016-04-12T15:21:50Z","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":5047,"stargazers_count":593,"watchers_count":593,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":295,"mirror_url":null,"open_issues_count":643,"forks":295,"open_issues":643,"watchers":593,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574"},"html":{"href":"https://github.com/rust-lang/rfcs/pull/1574"},"issue":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/1574"},"comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/issues/1574/comments"},"review_comments":{"href":"https://api.github.com/repos/rust-lang/rfcs/pulls/1574/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/1574/commits"},"statuses":{"href":"https://api.github.com/repos/rust-lang/rfcs/statuses/1330d7b6beafa21e6aab4e49d6ecff1cbbcb4e06"}}}}