|
Main /
JSDocWe use JSDoc to create .html documentation from the JavaScript .js files. JavaScript Accessors DocumentationJSDoc output, updated every 5 minutes
See Also
TagsSee Version 0 - 1a AccessorSpecification Documentation for a description of the tags
Run JSDocTo run JSDoc in your local tree, cd to The output will appear in JSDoc Formatting
JSDoc ArraysArrays should be specified as: * @output {array<{'horizontal': 'number', 'vertical': 'number'}>} cog The horizontal and vertical position of the center of gravity of motion, in pixels.
Not * @output {[number, number]} cog The horizontal and vertical position of the center of gravity of motion, in pixels.
Otherwise you will get [exec] ERROR: Unable to parse a tag's type expression for source file /Users/cxh/ptII/\ org/terraswarm/accessor/accessors/web/image/MotionDetector.js with tag title "output" and t\ ext "{[number, number]} cog The horizontal and vertical position of the center of gravity o\ f motion, in pixels.": Invalid type expression "[number, number]": Expected "!", "$", "'", \ "(", "*", ".", "...", "0", "?", "Function", "\"", "\\", "_", "break", "case", "catch", "cla\ ss", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", \ "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "inst\ anceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "r\ eturn", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined",\ "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase let\ ter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode upper\ case letter or [1-9] but "[" found. JSDoc Configuration
Below are the contents of { "plugins": ["plugins/markdown", "jsdoc/plugins/accessorJSDocTags"], "markdown": { "tags": ["accessor", "input", "output", "parameter"] }, "source": { "excludePattern": "(doc|browser/common|browser/test/lib|node_modules|vendors)" } }
jsdoc was failing with Comparison method violates its general contract! [exec] Parsing /home/jenkins/workspace/ptII/org/terraswarm/accessor/test/auto/accessors/DerivedA.js ... [exec] Generating output files... [exec] Exception in thread "main" java.lang.IllegalArgumentException: Comparison method violates its general contract! [exec] at java.util.TimSort.mergeLo(TimSort.java:777) [exec] at java.util.TimSort.mergeAt(TimSort.java:514) [exec] at java.util.TimSort.mergeCollapse(TimSort.java:441) [exec] at java.util.TimSort.sort(TimSort.java:245) [exec] at java.util.Arrays.sort(Arrays.java:1438) [exec] at org.mozilla.javascript.NativeArray.js_sort(NativeArray.java:1029) [exec] at org.mozilla.javascript.NativeArray.execIdCall(NativeArray.java:284) [exec] at org.mozilla.javascript.IdFunctionObject.call(IdFunctionObject.java:97) [exec] at org.mozilla.javascript.optimizer.OptRuntime.call1(OptRuntime.java:32) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_node_modules_taffydb_taffy_js_116._c_anonymous_25(Unknown Source) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_node_modules_taffydb_taffy_js_116.call(Unknown Source) [exec] at org.mozilla.javascript.optimizer.OptRuntime.callName(OptRuntime.java:63) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_node_modules_taffydb_taffy_js_116._c_anonymous_98(Unknown Source) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_node_modules_taffydb_taffy_js_116.call(Unknown Source) [exec] at org.mozilla.javascript.optimizer.OptRuntime.call1(OptRuntime.java:32) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_templates_default_publish_js_117._c_anonymous_38(Unknown Source) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_templates_default_publish_js_117.call(Unknown Source) [exec] at org.mozilla.javascript.optimizer.OptRuntime.callN(OptRuntime.java:52) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_cli_js_21._c_anonymous_28(Unknown Source) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_cli_js_21.call(Unknown Source) [exec] at org.mozilla.javascript.optimizer.OptRuntime.callProp0(OptRuntime.java:85) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_cli_js_21._c_anonymous_25(Unknown Source) [exec] at org.mozilla.javascript.gen.file__home_jenkins_workspace_ptII_vendors_jsdoc_cli_js_21.call(Unknown Source) [exec] at org.mozilla.javascript.optimizer.OptRuntime.callProp0(OptRuntime.java:85) It looks like the problem is trying to run jsdoc on mocha.js. The fix is to exclude browser/test/lib from jsdoc by adding that path to jsdoc.js. This problem does not occur in the default JSDoc that does not include our accessor hacks. PtDocIn Vergil, when an accessor is loaded or reloaded, a doc file is also downloaded and the contents of the doc file are merged in to the model. The doc file ends in For example, the accessor https://ptolemy.berkeley.edu/accessors/cameras/Camera.js has a corresponding PtDoc file: https://ptolemy.berkeley.edu/accessors/cameras/CameraPtDoc.xml The *.js files are read in and we use a plugin and a template to create *PtDoc.xml output. To run this: cd accessors/web ant ptdoc What happens is that ant runs jsdoc with the following command line options:
PtDoc Plugin
exports.defineTags = function(dictionary) { dictionary.defineTag("accessor", { mustHaveValue: true, onTagged: function(doclet, tag) { doclet.accessor = tag.name; } }); dictionary.defineTag("input", { mustHaveValue: true, canHaveType: true, canHaveName: true, onTagged: function(doclet, tag) { if (!doclet.inputs) { doclet.inputs = []; } doclet.inputs.push(tag.value); } }); dictionary.defineTag("output", { mustHaveValue: true, canHaveType: true, canHaveName: true, onTagged: function(doclet, tag) { if (!doclet.outputs) { doclet.outputs = []; } doclet.outputs.push(tag.value); } }); dictionary.defineTag("parameter", { mustHaveValue: true, canHaveType: true, canHaveName: true, onTagged: function(doclet, tag) { if (!doclet.parameters) { doclet.parameters = []; } doclet.parameters.push(tag.value); } }); }; What the above code does is push values for the For notes, see: https://chess.eecs.berkeley.edu/ptexternal/wiki/Main/JSDoc#JSDocCustomTags PtDoc TemplateThe template file at Continuous IntegrationOn terra.eecs.berkeley.edu we are running a job that checks for updates to the TerraSwarm accessors svn repo every five minutes. If there is a change to the svn repo, then The output appears at
ProblemsInput documentation missing in Vergil
The Camera.js accessor file has: * @input trigger A trigger input for triggered mode. but the docs output has: <property name="trigger (port-parameter)" class="ptolemy.kernel.util.StringAttribute" value="undefined A trigger input for triggered mode."> </property> The Input Ports input No port description. Interestingly, the output port doc works.
|