auto merge of #17432 : nick29581/rust/contrib, r=brson

[rust.git] / src / doc / rustdoc.md
diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md

index af69c6c1f7f159ada6e2115c991d707b55b0277d..07a93e58456b94a680378e960193788db994c7b7 100644 (file)
--- a/src/doc/rustdoc.md
+++ b/src/doc/rustdoc.md
@@ -51,7 +51,7 @@ 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)} }
+pub fn factorial(n: int) -> int { if n < 2 {1} else {n * factorial(n - 1)} }
  # fn main() {}
  ~~~
  
@@ -103,6 +103,17 @@ rustdoc can also generate JSON, for consumption by other tools, with
  `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
@@ -171,6 +182,18 @@ You can specify that the code block should be compiled but not run with the
  ```
  ~~~
  
+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
@@ -226,16 +249,16 @@ 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
+- `--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).