Some rustdoc manual fixes

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

Author: emberian

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