Permalink
Browse files

expand comments doc

  • Loading branch information...
1 parent 6cdc15b commit e976db8bc739c7851e8e03970cc327c1a78b4617 @nathantypanski nathantypanski committed Jun 30, 2014
Showing with 45 additions and 5 deletions.
  1. +45 −5 style/comments.md
View
@@ -14,13 +14,53 @@ Use line comments instead:
pub fn spawn(f: proc():Send) { ... }
```
-### Style doc comments like sentences.
+## Doc comments
-Doc comments should begin with capital letters and end in a period,
-even in the short summary description. Prefer full sentences to
-fragments.
+Doc comments are prefixed by three slashes (`///`) and indicate
+documentation that you would like to be included in Rustdoc's output.
+They support
+[Markdown syntax](http://daringfireball.net/projects/markdown/)
+and are the main way of documenting your public APIs.
-> **[FIXME]** Example.
+### Summary line
+
+The first line in any doc comment should be a single-line short sentence
+providing a summary of the code. This line is used as a short summary
+description throughout Rustdoc's output, so it's a good idea to keep it
+short.
+
+### Sentence structure
+
+All doc comments, including the summary line, should begin with a
+capital letter and ending with a period, question mark, or exclamation
+point. Prefer full sentences to fragments.
+
+For example:
+
+``` rust
+/// Set up a default runtime configuration, given compiler-supplied arguments.
+///
+/// This function will block until the entire pool of M:N schedulers have
+/// exited. This function also requires a local task to be available.
+///
+/// # Arguments
+///
+/// * `argc` & `argv` - The argument vector. On Unix this information is used
+/// by os::args.
+/// * `main` - The initial procedure to run inside of the M:N scheduling pool.
+/// Once this procedure exits, the scheduling pool will begin to shut
+/// down. The entire pool (and this function) will only return once
+/// all child tasks have finished executing.
+///
+/// # Return value
+///
+/// The return value is used as the process return code. 0 on success, 101 on
+/// error.
+```
+
+### Code snippets
+
+> **[OPEN]**
### Avoid inner doc comments.

0 comments on commit e976db8

Please sign in to comment.