Add rustdoc documentation.

doc/rustdoc.md

@@ -0,0 +1,72 @@
+% Rust Documentation
+
+`rustdoc` is the built-in tool for generating documentation. It integrates
+with the compiler to provide accurate hyperlinking between usage of types and
+their documentation. Furthermore, by not using a separate parser, it will
+never reject your valid Rust code.
+
+# Creating Documentation
+
+Documenting Rust APIs is quite simple. To document a given item, we have "doc
+comments":
+
+~~~
+// the "link" crate attribute is currently required for rustdoc, but normally
+// isn't needed.
+#[link(name="universe")];
+#[crate_type="lib"];
+
+//! Tools for dealing with universes (this is a doc comment, and is shown on
+//! the crate index page. The ! makes it apply to the parent of the comment,
+//! rather than what follows).
+
+/// Widgets are very common (this is a doc comment, and will show up on
+/// Widget's documentation).
+pub struct Widget {
+	/// All widgets have a purpose (this is a doc comment, and will show up
+	/// the field's documentation).
+	purpose: ~str,
+	/// Humans are not allowed to understand some widgets
+	understandable: bool
+}
+
+pub fn recalibrate() {
+	//! Recalibrate a pesky universe (this is also a doc comment, like above,
+	//! the documentation will be applied to the *parent* item, so
+	//! `recalibrate`).
+	/* ... */
+}
+~~~
+
+Then, one can 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
+crate advertises that its documentation is hosted at a given URL.
+
+The generated output can be controlled with the `doc` crate attribute, which
+is how the above advertisement works. An example from the `libstd`
+documentation:
+
+~~~
+#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
+      html_favicon_url = "http://www.rust-lang.org/favicon.ico",
+      html_root_url = "http://static.rust-lang.org/doc/master")];
+~~~
+
+The `html_root_url` is the prefix that rustdoc will apply to any references to
+that crate's types etc.
+
+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`.
+
+# Using the Documentation
+
+The web pages generated by rustdoc present the same logical heirarchy that one
+writes a library with. Every kind of item (function, struct, etc) has its own
+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.

doc/tutorial.md

@@ -872,9 +872,9 @@ A *destructor* is a function responsible for cleaning up the resources used by
 an object when it is no longer accessible. Destructors can be defined to handle
 the release of resources like files, sockets and heap memory.
 
-Objects are never accessible after their destructor has been called, so there
-are no dynamic failures from accessing freed resources. When a task fails, the
-destructors of all objects in the task are called.
+Objects are never accessible after their destructor has been called, so no
+dynamic failures are possible from accessing freed resources. When a task
+fails, destructors of all objects in the task are called.
 
 The `~` sigil represents a unique handle for a memory allocation on the heap:
 
@@ -3254,6 +3254,7 @@ tutorials on individual topics.
 * [Containers and iterators][container]
 * [Error-handling and Conditions][conditions]
 * [Packaging up Rust code][rustpkg]
+* [Documenting Rust code][rustdoc]
 
 There is further documentation on the [wiki], however those tend to be even
 more out of date than this document.
@@ -3265,6 +3266,7 @@ more out of date than this document.
 [container]: tutorial-container.html
 [conditions]: tutorial-conditions.html
 [rustpkg]: tutorial-rustpkg.html
+[rustdoc]: tutorial-rustdoc.html
 
 [wiki]: https://github.com/mozilla/rust/wiki/Docs
 [wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools

mk/docs.mk

@@ -74,6 +74,13 @@ doc/rustpkg.html: rustpkg.md doc/version_info.html doc/rust.css \
 	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
 	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
 
+DOCS += doc/rustdoc.html
+doc/rustdoc.html: rustdoc.md doc/version_info.html doc/rust.css \
+				doc/favicon.inc
+	@$(call E, pandoc: $@)
+	$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
+	$(CFG_PANDOC) $(HTML_OPTS) --output=$@
+
 DOCS += doc/tutorial.html
 doc/tutorial.html: tutorial.md doc/version_info.html doc/rust.css \
 				doc/favicon.inc