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