auto merge of #10913 : cmr/rust/rustdoc_man, r=huonw

Clarify that it's sundown, and that we don't support magic

Author: bors

doc/rust.md

@@ -486,14 +486,12 @@ include:
 * `fmt!` : format data into a string
 * `env!` : look up an environment variable's value at compile time
 * `stringify!` : pretty-print the Rust expression given as an argument
-* `proto!` : define a protocol for inter-task communication
 * `include!` : include the Rust expression in the given file
 * `include_str!` : include the contents of the given file as a string
 * `include_bin!` : include the contents of the given file as a binary blob
 * `error!`, `warn!`, `info!`, `debug!` : provide diagnostic information.
 
-All of the above extensions, with the exception of `proto!`, are expressions
-with values. `proto!` is an item, defining a new name.
+All of the above extensions are expressions with values.
 
 ## Macros
 

doc/rustdoc.md

@@ -38,8 +38,21 @@ pub fn recalibrate() {
 }
 ~~~
 
-Then, one can run `rustdoc universe.rs`. By default, it generates a directory
-called `doc`, with the documentation for `universe` being in
+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
+is that the first paragrah will be used as the "summary" of an item in the
+generated documentation:
+
+~~~
+/// A whizbang. Does stuff. (this line is the summary)
+///
+/// Whizbangs are ...
+struct Whizbang;
+~~~
+
+To generate the docs, run `rustdoc universe.rs`. By default, it generates a
+directory called `doc`, with the documentation for `universe` being in
 `doc/universe/index.html`. If you are using other crates with `extern mod`,
 rustdoc will even link to them when you use their types, as long as their
 documentation has already been generated by a previous run of rustdoc, or the
@@ -70,3 +83,5 @@ color, and one can always click on a colored type to jump to its
 documentation. There is a search bar at the top, which is powered by some
 javascript and a statically-generated search index. No special web server is
 required for the search.
+
+[sundown]: https://github.com/vmg/sundown/

doc/tutorial.md

@@ -3235,7 +3235,7 @@ more out of date than this document.
 [container]: tutorial-container.html
 [conditions]: tutorial-conditions.html
 [rustpkg]: tutorial-rustpkg.html
-[rustdoc]: tutorial-rustdoc.html
+[rustdoc]: rustdoc.html
 
 [wiki]: https://github.com/mozilla/rust/wiki/Docs
 [wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools