diff options
| -rw-r--r-- | mk/docs.mk | 2 | ||||
| -rw-r--r-- | src/doc/rustdoc.md | 93 |
2 files changed, 55 insertions, 40 deletions
diff --git a/mk/docs.mk b/mk/docs.mk index f3fd94678ff..72ef088704c 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -26,7 +26,7 @@ DOCS := index tutorial guide-ffi guide-macros guide-lifetimes \ guide-tasks guide-container guide-pointers \ complement-cheatsheet guide-runtime \ - rust + rust rustdoc RUSTDOC_DEPS_rust := doc/full-toc.inc RUSTDOC_FLAGS_rust := --markdown-in-header=doc/full-toc.inc diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md index 415db46be5b..3359cd4f40d 100644 --- a/src/doc/rustdoc.md +++ b/src/doc/rustdoc.md @@ -20,6 +20,7 @@ comments": //! the crate index page. The ! makes it apply to the parent of the comment, //! rather than what follows). +# mod workaround_the_outer_function_rustdoc_inserts { /// Widgets are very common (this is a doc comment, and will show up on /// Widget's documentation). pub struct Widget { @@ -36,6 +37,7 @@ pub fn recalibrate() { //! `recalibrate`). /* ... */ } +# } ~~~ Doc comments are markdown, and are currently parsed with the @@ -94,7 +96,7 @@ source code. To test documentation, the `--test` argument is passed to rustdoc: -~~~ +~~~ {.notrust} rustdoc --test crate.rs ~~~ @@ -105,35 +107,44 @@ 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. -~~~ -``` -// This is a testable code block -``` + /** + # nested codefences confuse sundown => indentation + comment to + # avoid failing tests + ``` + // This is a testable code block + ``` -```ignore -// This is not a testable code block -``` + ```ignore + // This is not a testable code block + ``` - // This is a testable code block (4-space indent) -~~~ + // This is a testable code block (4-space indent) + */ + # fn foo() {} You can specify that the test's execution should fail with the `should_fail` directive. -~~~ -```should_fail -// This code block is expected to generate a failure when run -``` -~~~ + /** + # nested codefences confuse sundown => indentation + comment to + # avoid failing tests + ```should_fail + // This code block is expected to generate a failure when run + ``` + */ + # fn foo() {} You can specify that the code block should be compiled but not run with the `no_run` directive. -~~~ -```no_run -// This code will be compiled but not executed -``` -~~~ + /** + # nested codefences confuse sundown => indentation + comment to + # avoid failing tests + ```no_run + // This code will be compiled but not executed + ``` + */ + # fn foo() {} Rustdoc also supplies some extra sugar for helping with some tedious documentation examples. If a line is prefixed with `# `, then the line @@ -141,20 +152,23 @@ 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)]`). -~~~ -```rust -# /!\ 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 -# case, the character following the leading '#' is not a usual space like in -# these first five lines but a non breakable one. -# -# // showing 'fib' in this documentation would just be tedious and detracts from -# // what's actualy being documented. -# fn fib(n: int) { n + 2 } - -do spawn { fib(200); } -``` -~~~ + /** + # nested codefences confuse sundown => indentation + comment to + # avoid failing tests + ```rust + # /!\ 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 + # case, the character following the leading '#' is not a usual space like in + # these first five lines but a non breakable one. + # + # // showing 'fib' in this documentation would just be tedious and detracts from + # // what's actualy being documented. + # fn fib(n: int) { n + 2 } + + do spawn { fib(200); } + ``` + */ + # fn foo() {} The documentation online would look like `do spawn { fib(200); }`, but when testing this code, the `fib` function will be included (so it can compile). @@ -167,12 +181,12 @@ uses is build on crate `test`, which is also used when you compile crates with rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness with the `--test-args` flag. -~~~ -// Only run tests containing 'foo' in their name -rustdoc --test lib.rs --test-args 'foo' +~~~ {.notrust} +$ # Only run tests containing 'foo' in their name +$ rustdoc --test lib.rs --test-args 'foo' -// See what's possible when running tests -rustdoc --test lib.rs --test-args '--help' +$ # See what's possible when running tests +$ rustdoc --test lib.rs --test-args '--help' ~~~ When testing a library, code examples will often show how functions are used, @@ -189,6 +203,7 @@ into HTML and testing the code snippets from them. A Markdown file is detected by a `.md` or `.markdown` extension. 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 end of the `<head>...</head>` section. |