Recent Changes - Search:

edit SideBar

JSDoc

We use JSDoc to create .html documentation from the JavaScript .js files.

JavaScript Accessors Documentation

JSDoc output, updated every 5 minutes

See Also

Tags

See Version 0 - 1a AccessorSpecification Documentation for a description of the tags

@accessor
@input
@output
@parameter

Run JSDoc

To run JSDoc in your local tree, cd to accessors/web and run ant. The ant command will download jsdoc using npm install @terraswarm/jsdoc.

The output will appear in accessors/web/doc/jsdoc/index.html

JSDoc Formatting

JSDoc Arrays

Arrays 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

accessors/web/jsdoc/jsdoc.json is used to configure JSDoc.

Below are the contents of jsdoc.json ''Note that the version in the svn repo might be different

{
    "plugins": ["plugins/markdown", "jsdoc/plugins/accessorJSDocTags"],
    "markdown": {
        "tags": ["accessor", "input", "output", "parameter"]
    },
    "source": {
        "excludePattern": "(doc|browser/common|browser/test/lib|node_modules|vendors)"
    }
}
plugins
Causes jsdoc to use read accessors/web/jsdoc/accessorJSDocTags.js. This is use by the ptdoc template

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.

PtDoc

In 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 PtDoc.xml.

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:

--configure jsdoc/jsdoc.json
Use the configuration file from accessors/web/jsdoc/jsdoc.json which configures JSDoc to use the plugin at accessors/web/jsdoc/plugins/accessorJSDocTags.js.
--template jsdoc/templates/ptdoc
Use the template in accessors/web/jsdoc/templates/ptdoc/publish.js.

PtDoc Plugin

accessors/web/jsdoc/plugins/accessorJSDocTags.js looks like: Note that this may have changed, see https://ptolemy.berkeley.edu/accessors/jsdoc/plugins/accessorJSDocTags.js for an uptodate version''

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 @accessor etc. tags into JavaScript arrays.

For notes, see: https://chess.eecs.berkeley.edu/ptexternal/wiki/Main/JSDoc#JSDocCustomTags

PtDoc Template

The template file at accessors/web/jsdoc/templates/ptdoc/publish.js (See https://ptolemy.berkeley.edu/accessors/jsdoc/templates/ptdoc/publish.js) defines a JavaScript function called publish() that gets invoked by JSDoc.

Continuous Integration

On 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 ant is run and JSDoc invoked on the .js files.

The output appears at

Problems

Input documentation missing in Vergil

  1. PTII/bin/vergil $PTII/org/terraswarm/accessor/demo/Camera/Camera.xml
  2. Then click on the Camera Accessor and then click Reload.
  3. Then right click on the Camera Accessor and select Documentation -> Get Documentation.

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.


Edit - History - Print - Recent Changes - Search
Page last modified on December 25, 2016, at 02:05 PM