comments":
~~~
+# #![allow(unused_attribute)]
// the "link" crate attribute is currently required for rustdoc, but normally
// isn't needed.
#![crate_id = "universe"]
pub struct Widget {
/// All widgets have a purpose (this is a doc comment, and will show up
/// the field's documentation).
- purpose: StrBuf,
+ purpose: String,
/// Humans are not allowed to understand some widgets
understandable: bool
}
# }
~~~
+Documentation can also be controlled via the `doc` attribute on items. This is
+implicitly done by the compiler when using the above form of doc comments
+(converting the slash-based comments to `#[doc]` attributes).
+
+~~~
+#[doc = "
+Calculates the factorial of a number.
+
+Given the input integer `n`, this function will calculate `n!` and return it.
+"]
+pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} }
+# fn main() {}
+~~~
+
+The `doc` attribute can also be used to control how rustdoc emits documentation
+in some cases.
+
+```
+// Rustdoc will inline documentation of a `pub use` into this crate when the
+// `pub use` reaches across crates, but this behavior can also be disabled.
+#[doc(no_inline)]
+pub use std::option::Option;
+# fn main() {}
+```
+
Doc comments are markdown, and are currently parsed with the
[sundown][sundown] library. rustdoc does not yet do any fanciness such as
referencing other items inline, like javadoc's `@see`. One exception to this
`rustdoc --output-format json`, and also consume already-generated JSON with
`rustdoc --input-format json`.
+rustdoc also supports personalizing the output from crates' documentation,
+similar to markdown options.
+
+- `--html-in-header FILE`: includes the contents of `FILE` at the
+ end of the `<head>...</head>` section.
+- `--html-before-content FILE`: includes the contents of `FILE`
+ directly after `<body>`, before the rendered content (including the
+ search bar).
+- `--html-after-content FILE`: includes the contents of `FILE`
+ after all the rendered content.
+
# Using the Documentation
The web pages generated by rustdoc present the same logical hierarchy that one
To test documentation, the `--test` argument is passed to rustdoc:
-~~~ {.notrust}
+~~~ {.sh}
rustdoc --test crate.rs
~~~
## Defining tests
Rust documentation currently uses the markdown format, and rustdoc treats all
-code blocks as testable-by-default. In order to not run a test over a block of
-code, the `ignore` string can be added to the three-backtick form of markdown
-code block.
+code blocks as testable-by-default unless they carry a language tag of another
+language. In order to not run a test over a block of code, the `ignore` string
+can be added to the three-backtick form of markdown code block.
-~~~notrust
+~~~md
```
// This is a testable code block
```
+```rust{.example}
+// This is rust and also testable
+```
+
```ignore
// This is not a testable code block
```
// This is a testable code block (4-space indent)
+
+```sh
+# this is shell code and not tested
+```
~~~
You can specify that the test's execution should fail with the `should_fail`
directive.
-~~~notrust
+~~~md
```should_fail
// This code block is expected to generate a failure when run
```
You can specify that the code block should be compiled but not run with the
`no_run` directive.
-~~~notrust
+~~~md
```no_run
// This code will be compiled but not executed
```
~~~
+Lastly, you can specify that a code block be compiled as if `--test`
+were passed to the compiler using the `test_harness` directive.
+
+~~~md
+```test_harness
+#[test]
+fn foo() {
+ fail!("oops! (will run & register as failure)")
+}
+```
+~~~
+
Rustdoc also supplies some extra sugar for helping with some tedious
documentation examples. If a line is prefixed with `# `, then the line
will not show up in the HTML documentation, but it will be used when
testing the code block (NB. the space after the `#` is required, so
that one can still write things like `#[deriving(Eq)]`).
-~~~notrust
+~~~md
```
# /!\ The three following lines are comments, which are usually stripped off by
# the doc-generating tool. In order to display them anyway in this particular
rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness
with the `--test-args` flag.
-~~~ {.notrust}
+~~~console
# Only run tests containing 'foo' in their name
$ rustdoc --test lib.rs --test-args 'foo'
There are 4 options to modify the output that Rustdoc creates.
- `--markdown-css PATH`: adds a `<link rel="stylesheet">` tag pointing to `PATH`.
-- `--markdown-in-header FILE`: includes the contents of `FILE` at the
+- `--html-in-header FILE`: includes the contents of `FILE` at the
end of the `<head>...</head>` section.
-- `--markdown-before-content FILE`: includes the contents of `FILE`
+- `--html-before-content FILE`: includes the contents of `FILE`
directly after `<body>`, before the rendered content (including the
title).
-- `--markdown-after-content FILE`: includes the contents of `FILE`
+- `--html-after-content FILE`: includes the contents of `FILE`
directly before `</body>`, after all the rendered content.
All of these can be specified multiple times, and they are output in
-the order in which they are specified. The first line of the file must
+the order in which they are specified. The first line of the file being rendered must
be the title, prefixed with `%` (e.g. this page has `% Rust
Documentation` on the first line).
projects / rust.git / blobdiff