| OLD | NEW |
|---|
| (Empty) |
| 1 Apidoc is a specialization of Dartdoc. | |
| 2 Dartdoc generates static HTML documentation from Dart code. | |
| 3 Apidoc wraps the dartdoc output with official dartlang.org skin, comments, etc. | |
| 4 | |
| 5 To use it, from the top level dart directory, run: | |
| 6 | |
| 7 $ dart utils/apidoc/apidoc.dart [--out=<output directory>] | |
| 8 | |
| 9 This will create a "docs" directory with the docs for your libraries. | |
| 10 | |
| 11 | |
| 12 How docs are generated | |
| 13 ---------------------- | |
| 14 | |
| 15 To make beautiful docs from your library, dartdoc parses it and every library it | |
| 16 imports (recursively). From each library, it parses all classes and members, | |
| 17 finds the associated doc comments and builds crosslinked docs from them. | |
| 18 | |
| 19 "Doc comments" can be in one of a few forms: | |
| 20 | |
| 21 /** | |
| 22 * JavaDoc style block comments. | |
| 23 */ | |
| 24 | |
| 25 /** Which can also be single line. */ | |
| 26 | |
| 27 /// Triple-slash line comments. | |
| 28 /// Which can be multiple lines. | |
| 29 | |
| 30 The body of a doc comment will be parsed as markdown which means you can apply | |
| 31 most of the formatting and structuring you want while still having docs that | |
| 32 look nice in plain text. For example: | |
| 33 | |
| 34 /// This is a doc comment. This is the first paragraph in the comment. It | |
| 35 /// can span multiple lines. | |
| 36 /// | |
| 37 /// A blank line starts a new paragraph like this one. | |
| 38 /// | |
| 39 /// * Unordered lists start with `*` or `-` or `+`. | |
| 40 /// * And can have multiple items. | |
| 41 /// 1. You can nest lists. | |
| 42 /// 2. Like this numbered one. | |
| 43 /// | |
| 44 /// --- | |
| 45 /// | |
| 46 /// Three dashes, underscores, or tildes on a line by themselves create a | |
| 47 /// horizontal rule. | |
| 48 /// | |
| 49 /// to.get(a.block + of.code) { | |
| 50 /// indent(it, 4.lines); | |
| 51 /// like(this); | |
| 52 /// } | |
| 53 /// | |
| 54 /// There are a few inline styles you can apply: *emphasis*, **strong**, | |
| 55 /// and `inline code`. You can also use underscores for _emphasis_ and | |
| 56 /// __strong__. | |
| 57 /// | |
| 58 /// An H1 header using equals on the next line | |
| 59 /// ========================================== | |
| 60 /// | |
| 61 /// And an H2 in that style using hyphens | |
| 62 /// ------------------------------------- | |
| 63 /// | |
| 64 /// # Or an H1 - H6 using leading hashes | |
| 65 /// ## H2 | |
| 66 /// ### H3 | |
| 67 /// #### H4 you can also have hashes at then end: ### | |
| 68 /// ##### H5 | |
| 69 /// ###### H6 | |
| 70 | |
| 71 There is also an extension to markdown specific to dartdoc: A name inside | |
| 72 square brackets that is not a markdown link (i.e. doesn't have square brackets | |
| 73 or parentheses following it) like: | |
| 74 | |
| 75 Calls [someMethod], passing in [arg]. | |
| 76 | |
| 77 is understood to be the name of some member or type that's in the scope of the | |
| 78 member where that comment appears. Dartdoc will automatically figure out what | |
| 79 the name refers to and generate an approriate link to that member or type. | |
| 80 | |
| 81 | |
| 82 Attribution | |
| 83 ----------- | |
| 84 | |
| 85 dartdoc uses the delightful Silk icon set by Mark James. | |
| 86 http://www.famfamfam.com/lab/icons/silk/ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1361163002:
remove docgen remnants from repo, update CHANGELOG (Closed)
Base URL: https://github.com/dart-lang/sdk.git@master