Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

expand comments doc

  • Loading branch information
nathantypanski committed Jun 30, 2014
1 parent 6cdc15b commit e976db8bc739c7851e8e03970cc327c1a78b4617
Showing with 45 additions and 5 deletions.
  1. +45 −5 style/comments.md
@@ -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.
You can’t perform that action at this time.