1 | # Command line usage example
|
2 |
|
3 | ```
|
4 | jsdoc -c jsdoc.json -r -t docs -d gen/docs lib
|
5 | ```
|
6 |
|
7 | - `-c`: use this config file for `jsdoc`
|
8 | - `-r`: Recurse into subdirectories of the specified source directories
|
9 | - `-t`: Use template in path `docs`
|
10 | - `-d`: Generated html files put in `gen/docs`
|
11 | - Source files to parse are taken from directory `lib`
|
12 |
|
13 |
|
14 | ## Notes
|
15 |
|
16 | The template generation is set up so that:
|
17 |
|
18 | - Files ending in `.tmpl` are skipped
|
19 | - All non-html files are plain copied
|
20 | - html-files *can* contain `<?js ?>` tags, but this is not required
|
21 |
|
22 |
|
23 | ## Intention
|
24 |
|
25 | The `docs` directory is treated as a `jsdoc` template, in which the html-files are the template files. This allows for a gradual adaptation of the html-files to templates; unchanged html-files will pass through `jsdoc` unchanged.
|
26 |
|
27 | The added value of using `jsdoc` for documentation generation, is that the complete documentation information, as collected by `jsdoc` from the source, is available for usage. This way, it's possible to insert technical notes from the source code into the documentation.
|
28 |
|
29 | ----
|
30 |
|
31 | # Usage of and Notes on Source Code
|
32 |
|
33 | This section contains notes on the usage of `jsdoc` functionality, to aid with the handling of its generated data.
|
34 |
|
35 |
|
36 | ## Parameters of `publish()`
|
37 |
|
38 | ### Parameter `taffyData`
|
39 |
|
40 | A table containing *all* data collected from the source code, related to jsdoc generation. See below for more info and example outputs.
|
41 |
|
42 | ### Parameter `opt`
|
43 |
|
44 | Example of `opt` variable:
|
45 |
|
46 | ```js
|
47 | {
|
48 | "_":["../github/vis/lib/network/"],
|
49 | "configure":"jsdoc.json",
|
50 | "recurse":true,
|
51 | "template":"/home/wim/projects/jsdoc/default",
|
52 | "destination":"./out/",
|
53 | "encoding":"utf8"
|
54 | }
|
55 | ```
|
56 |
|
57 | ### Parameter `tutorial`
|
58 |
|
59 | This does not appear to be of use for the generation of `vis.js` documentation.
|
60 |
|
61 | Example of `tutorial` variable:
|
62 |
|
63 | ```js
|
64 | {
|
65 | "longname":"",
|
66 | "name":"",
|
67 | "title":"",
|
68 | "content":"",
|
69 | "parent":null,
|
70 | "children":[],
|
71 | "_tutorials":{}
|
72 | }
|
73 | ```
|
74 |
|
75 | ## Global variable `env`
|
76 |
|
77 | This contains addition info for the current execution of `jsdoc`. Example of `env` variable:
|
78 |
|
79 | ```js
|
80 | {
|
81 | "run":{"start":"2017-09-16T05:06:45.621Z","finish":null},
|
82 | "args":["-c","jsdoc.json","-r","-t","default","../github/vis/lib/network/"],
|
83 | "conf":{
|
84 | "plugins":["/usr/lib/node_modules/jsdoc/plugins/markdown.js"],
|
85 | "recurseDepth":10,
|
86 | "source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":""},
|
87 | "sourceType":"module",
|
88 | "tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},
|
89 | "templates":{"monospaceLinks":false,"cleverLinks":false}
|
90 | },
|
91 | "dirname":"/usr/lib/node_modules/jsdoc",
|
92 | "pwd":"/home/wim/projects/jsdoc",
|
93 | "opts":{ <<same as parameter 'opt' above>> },
|
94 | "sourceFiles":[ <<list of full path names of all js-source files used as input>> ],
|
95 | "version":{"number":"3.5.4","revision":"Fri, 04 Aug 2017 22:05:27 GMT"}
|
96 | }
|
97 | ```
|
98 |
|
99 |
|
100 | ## taffyData
|
101 |
|
102 | This is a parameter to `publish()`. It's a table containing *all* data collected from the source code, related to jsdoc generation.
|
103 |
|
104 | I can't find any way to return a list of fields for the data items in the taffyDB docs, therefore below there are examples of items, for better understanding of usage.
|
105 |
|
106 | Example usage:
|
107 |
|
108 | ```js
|
109 | var data = taffyData;
|
110 | var tmp = data().filter({name:'Label'}).get();
|
111 | ```
|
112 |
|
113 | Returns an array with all items with `name === 'Label'`. Example output of one of these items, for a class:
|
114 |
|
115 | *In these examples, block comment endings are redacted to ' * /'*
|
116 |
|
117 | ```js
|
118 | {
|
119 | "comment":"/**\n * A Label to be used for Nodes or Edges.\n * /",
|
120 | "meta":{
|
121 | "range":[3770,41303],
|
122 | "filename":"Label.js",
|
123 | "lineno":167,
|
124 | "columnno":0,
|
125 | "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
|
126 | "code":{
|
127 | "id":"astnode100065034",
|
128 | "name":"Label",
|
129 | "type":"ClassDeclaration",
|
130 | "paramnames":["body","options","edgelabel"]
|
131 | }
|
132 | },
|
133 | "classdesc":"
|
134 | A Label to be used for Nodes or Edges.
|
135 |
|
136 | ",
|
137 | "name":"Label",
|
138 | "longname":"Label",
|
139 | "kind":"class",
|
140 | "scope":"global",
|
141 | "params":[
|
142 | {"type":{"names":["Object"]},"name":"body"},
|
143 | {"type":{"names":["Object"]},"name":"options"},
|
144 | {"type":{"names":["boolean"]},"optional":true,"defaultvalue":false,"name":"edgelabel"}
|
145 | ],
|
146 | "___id":"T000002R005289",
|
147 | "___s":true
|
148 | }
|
149 | ```
|
150 |
|
151 | Example of item for an instance method:
|
152 |
|
153 | ```js
|
154 | var tmp = data().filter({name:'_drawText'}).get();
|
155 | ```
|
156 |
|
157 | Full output returned:
|
158 |
|
159 | ```js
|
160 | [{
|
161 | "comment":"/**\n *\n * @param {CanvasRenderingContext2D} ctx\n * @param {boolean} selected\n * @param {boolean} hover\n * @param {number} x\n * @param {number} y\n * @param {string} [baseline='middle']\n * @private\n * /",
|
162 | "meta":{
|
163 | "range":[20060,22269],
|
164 | "filename":"Label.js",
|
165 | "lineno":652,
|
166 | "columnno":2,
|
167 | "path":"/home/wim/projects/github/vis/lib/network/modules/components/shared",
|
168 | "code":{
|
169 | "id":"astnode100066427",
|
170 | "name":"Label#_drawText",
|
171 | "type":"MethodDefinition",
|
172 | "paramnames":["ctx","selected","hover","x","y","baseline"]
|
173 | },
|
174 | "vars":{"":null}
|
175 | },
|
176 | "params":[
|
177 | {"type":{"names":["CanvasRenderingContext2D"]},"name":"ctx"},
|
178 | {"type":{"names":["boolean"]},"name":"selected"},
|
179 | {"type":{"names":["boolean"]},"name":"hover"},
|
180 | {"type":{"names":["number"]},"name":"x"},
|
181 | {"type":{"names":["number"]},"name":"y"},
|
182 | {"type":{"names":["string"]},"optional":true,"defaultvalue":"'middle'","name":"baseline"}
|
183 | ],
|
184 | "access":"private",
|
185 | "name":"_drawText",
|
186 | "longname":"Label#_drawText",
|
187 | "kind":"function",
|
188 | "memberof":"Label",
|
189 | "scope":"instance",
|
190 | "___id":"T000002R005388",
|
191 | "___s":true
|
192 | }]
|
193 | ```
|
194 |
|
195 | ## `jsdoc` template rendering
|
196 |
|
197 | See `function createRenderer(fromDir, data)` in code for usage.
|
198 |
|
199 | There are two calls for rendering templates:
|
200 |
|
201 | - `var html = renderer.render(inFile, docData);`
|
202 | - `var html = renderer.partial(inFile, docData);`
|
203 |
|
204 | The difference is that `render()` will use a default layout template, if present, which will encapsulate all html. This can be set by:
|
205 |
|
206 | ```js
|
207 | renderer.layout = 'path/to/default/layout.tmpl';
|
208 | ```
|
209 |
|
210 | Parameter `docData` is a hash which is used to pass parameters into a template. The standard way of using this appear to be:
|
211 |
|
212 | ```
|
213 | <?js
|
214 | var data = obj; // Whatever docData is
|
215 | var self = this;
|
216 | ?>
|
217 | ```
|
218 |
|
219 | But it also appear to be possible to use the elements of docData directly:
|
220 |
|
221 | ```js
|
222 | var docData = {
|
223 | myTitle: 'Hello, pussycat!'
|
224 | };
|
225 | ```
|
226 |
|
227 | Within the template:
|
228 |
|
229 | ```
|
230 | <?js= myTitle ?>
|
231 | ```
|