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 |