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/
@@ -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
+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](
+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
+### 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.