mirror of
https://github.com/dart-lang/sdk
synced 2024-09-19 14:32:49 +00:00
114c3836e0
Review URL: https://chromiumcodereview.appspot.com//10389223 git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@7779 260f80e4-7a28-3924-810f-c04153c831b5
87 lines
2.8 KiB
Plaintext
87 lines
2.8 KiB
Plaintext
Apidoc is a specialization of Dartdoc.
|
|
Dartdoc generates static HTML documentation from Dart code.
|
|
Apidoc wraps the dartdoc output with official dartlang.org skin, comments, etc.
|
|
|
|
To use it, from the top level dart directory, run:
|
|
|
|
$ dart utils/apidoc/apidoc.dart [--out=<output directory>]
|
|
|
|
This will create a "docs" directory with the docs for your libraries.
|
|
|
|
|
|
How docs are generated
|
|
----------------------
|
|
|
|
To make beautiful docs from your library, dartdoc parses it and every library it
|
|
imports (recursively). From each library, it parses all classes and members,
|
|
finds the associated doc comments and builds crosslinked docs from them.
|
|
|
|
"Doc comments" can be in one of a few forms:
|
|
|
|
/**
|
|
* JavaDoc style block comments.
|
|
*/
|
|
|
|
/** Which can also be single line. */
|
|
|
|
/// Triple-slash line comments.
|
|
/// Which can be multiple lines.
|
|
|
|
The body of a doc comment will be parsed as markdown which means you can apply
|
|
most of the formatting and structuring you want while still having docs that
|
|
look nice in plain text. For example:
|
|
|
|
/// This is a doc comment. This is the first paragraph in the comment. It
|
|
/// can span multiple lines.
|
|
///
|
|
/// A blank line starts a new paragraph like this one.
|
|
///
|
|
/// * Unordered lists start with `*` or `-` or `+`.
|
|
/// * And can have multiple items.
|
|
/// 1. You can nest lists.
|
|
/// 2. Like this numbered one.
|
|
///
|
|
/// ---
|
|
///
|
|
/// Three dashes, underscores, or tildes on a line by themselves create a
|
|
/// horizontal rule.
|
|
///
|
|
/// to.get(a.block + of.code) {
|
|
/// indent(it, 4.lines);
|
|
/// like(this);
|
|
/// }
|
|
///
|
|
/// There are a few inline styles you can apply: *emphasis*, **strong**,
|
|
/// and `inline code`. You can also use underscores for _emphasis_ and
|
|
/// __strong__.
|
|
///
|
|
/// An H1 header using equals on the next line
|
|
/// ==========================================
|
|
///
|
|
/// And an H2 in that style using hyphens
|
|
/// -------------------------------------
|
|
///
|
|
/// # Or an H1 - H6 using leading hashes
|
|
/// ## H2
|
|
/// ### H3
|
|
/// #### H4 you can also have hashes at then end: ###
|
|
/// ##### H5
|
|
/// ###### H6
|
|
|
|
There is also an extension to markdown specific to dartdoc: A name inside
|
|
square brackets that is not a markdown link (i.e. doesn't have square brackets
|
|
or parentheses following it) like:
|
|
|
|
Calls [someMethod], passing in [arg].
|
|
|
|
is understood to be the name of some member or type that's in the scope of the
|
|
member where that comment appears. Dartdoc will automatically figure out what
|
|
the name refers to and generate an approriate link to that member or type.
|
|
|
|
|
|
Attribution
|
|
-----------
|
|
|
|
dartdoc uses the delightful Silk icon set by Mark James.
|
|
http://www.famfamfam.com/lab/icons/silk/
|