Add rustdoc documentation.
This commit is contained in:
parent
039a5933fb
commit
94e0a03f5d
3 changed files with 84 additions and 3 deletions
72
doc/rustdoc.md
Normal file
72
doc/rustdoc.md
Normal file
|
@ -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.
|
|
@ -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
|
an object when it is no longer accessible. Destructors can be defined to handle
|
||||||
the release of resources like files, sockets and heap memory.
|
the release of resources like files, sockets and heap memory.
|
||||||
|
|
||||||
Objects are never accessible after their destructor has been called, so there
|
Objects are never accessible after their destructor has been called, so no
|
||||||
are no dynamic failures from accessing freed resources. When a task fails, the
|
dynamic failures are possible from accessing freed resources. When a task
|
||||||
destructors of all objects in the task are called.
|
fails, destructors of all objects in the task are called.
|
||||||
|
|
||||||
The `~` sigil represents a unique handle for a memory allocation on the heap:
|
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]
|
* [Containers and iterators][container]
|
||||||
* [Error-handling and Conditions][conditions]
|
* [Error-handling and Conditions][conditions]
|
||||||
* [Packaging up Rust code][rustpkg]
|
* [Packaging up Rust code][rustpkg]
|
||||||
|
* [Documenting Rust code][rustdoc]
|
||||||
|
|
||||||
There is further documentation on the [wiki], however those tend to be even
|
There is further documentation on the [wiki], however those tend to be even
|
||||||
more out of date than this document.
|
more out of date than this document.
|
||||||
|
@ -3265,6 +3266,7 @@ more out of date than this document.
|
||||||
[container]: tutorial-container.html
|
[container]: tutorial-container.html
|
||||||
[conditions]: tutorial-conditions.html
|
[conditions]: tutorial-conditions.html
|
||||||
[rustpkg]: tutorial-rustpkg.html
|
[rustpkg]: tutorial-rustpkg.html
|
||||||
|
[rustdoc]: tutorial-rustdoc.html
|
||||||
|
|
||||||
[wiki]: https://github.com/mozilla/rust/wiki/Docs
|
[wiki]: https://github.com/mozilla/rust/wiki/Docs
|
||||||
[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools
|
[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools
|
||||||
|
|
|
@ -74,6 +74,13 @@ doc/rustpkg.html: rustpkg.md doc/version_info.html doc/rust.css \
|
||||||
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
|
$(Q)$(CFG_NODE) $(S)doc/prep.js --highlight $< | \
|
||||||
$(CFG_PANDOC) $(HTML_OPTS) --output=$@
|
$(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
|
DOCS += doc/tutorial.html
|
||||||
doc/tutorial.html: tutorial.md doc/version_info.html doc/rust.css \
|
doc/tutorial.html: tutorial.md doc/version_info.html doc/rust.css \
|
||||||
doc/favicon.inc
|
doc/favicon.inc
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue