• View
• Edit
• History
• Print

JSDoc

JSDoc Public Output

JSDoc output, updated every 5 minutes

• JSDoc output for accessors (accessors workgroup)
• JSDoc output for ptII accessors (ptII repo)

See Also

• JS
• JSDoc (accessors workgroup)
• JSDoc Modifications For Accessor Tags How JSDoc was modified to support @accessor, @input, @output and @parameter
• JS Formatters

JSDoc

• http://usejsdoc.org/
• Eclipse JavaScript cleanup supports JSDoc

JSDoc Summary

• We have a custom branch of JSDoc that understands accessor tags at https://github.com/terraswarm/jsdoc.git
• There are two places where JSDoc output occurs:

1. TerraSwarm accessors repo

   • Location in the ptII tree: $PTII/org/terraswarm/accessor/accessors/web/doc/jsdoc/index.html
   • Automatically updated location: JSDoc output for accessors (accessors workgroup)
   • org/terraswarm/accessor/accessors/web/build.xml contains the jsdoc target that creates the output
     • The custom jsdoc branch is downloaded automatically by JSAccessor.getAccessorsRepository() to $PTII/org/terraswarm/accessor/accessors/web/vendors/jsdoc/

2. PtII repo that contains docs for actor/lib/jjs

   • Location in the ptII tree: $PTII/doc/codeDoc/js/index.html
   • Automatically updated location: JSDoc output for ptII accessors (ptII repo)
   • $PTII/build.xml contains the jsdoc target that creates the output
     • The custom jsdoc branch is also downloaded to $PTII/doc/vendors/jsdoc
       • We download the custom jsdoc branch twice because we want each repo to be standalone

Problems and solutions for JSDoc writers

The message "Unable to parse a tag's type expression for source file" appears

See https://www.terraswarm.org/accessors/wiki/Main/JSDoc#JSDocArrays

JSDoc Implementation Details

How JSDoc creates the PtDoc.xml files

Summary: running (cd $PTII/org/terraswarm/accessor/accessors/web; ant) or reloading an accessor runs a custom version of JSDoc that reads org/terraswarm/accessor/accessors/web/jsdoc/templates/ptdoc/publish.js and generates PtDoc.xml files like $PTII/org/terraswarm/accessor/accessors/web/audio/AudioCapturePtDoc.xml

Details:

Keep in mind that we can run jsdoc in two locations, the terraswarm accessors repo and the ptII repo.

Here, we discuss how files like $PTII/org/terraswarm/accessor/accessors/web/audio/AudioCapturePtDoc.xml are created, see https://www.terraswarm.org/accessors/audio/AudioCapturePtDoc.xml for example:

The *PtDoc.xml files for the TerraSwarm accessors repo are created by running ant in accessors/web, which is in the ptII tree as $PTII/org/terraswarm/accessor/accessors/web/build.xml. The JSAccessor.getAccessorsRepository() method runs ant for us when the accessors are reloaded. The terraswarm website gets updated via continuous integration.

The way ant works is that it reads in accessors/web/build.xml, which names the default target as being the build target. The build target has two dependency targets: jsdoc and ptdoc that get invoked.

The ptdoc target looks like:

The ptdoc target has a dependency target vendors-jsdoc which downloads our custom branch of jsdoc.

To invoke the command by hand:

To see what command is invoked:

To run jsdoc by hand to build ptdoc files:

The template directory is jsdoc/templates/ptdoc, which maps to org/terraswarm/accessor/accessors/web/jsdoc/templates/ptdoc/

In that directory is a publish.js file that defines methods that are PtDoc specific.

JSDoc Simple Example

This example downloads the non-accessor-specifc JSDoc code and runs it on the Ptolemy II .js files. This example is an illustration of getting started with JSDoc, instead of following this example, we now have a custom branch of JSDoc, ant rules and Java code that invokes the ant rules

1. Download into $PTII/vendors:
   cd $PTII/vendors
   git clone https://github.com/jsdoc3/jsdoc

   [$[Get Code]]
2. Run jsdoc
   cd $PTII
   vendors/jsdoc/jsdoc --recurse ptolemy/actor/lib/jjs

   [$[Get Code]]
3. The output is in $PTII/out/index.html

JSDoc Ant Ptolemy Example

We now have an ant rule that generates JSDoc output in $PTII/doc/codeDoc/js/index.html

1. Update your tree and regenerate $PTII/build.xml
   cd $PTII
   svn update
   ./configure

   [$[Get Code]]
2. Invoke ant:
   ant jsdoc

   [$[Get Code]]
3. View the output
   open doc/codeDoc/js/index.html

   [$[Get Code]]

Note that the file $PTII/doc/jsdoc/topREADME.md is used to create $PTII/doc/codeDoc/js/index.html. The way this works is that we pass a -R argument to jsdoc in $PTII/build.xml.

For formatting instructions see Getting Started and Block Tags

Continuous Integration

We use continuous integration to update the websites with the documentation.

Recall from above that the docs appear on both the CHESS website and the TerraSwarm website.

• https://chess.eecs.berkeley.edu/ptexternal/src/ptII/doc/codeDoc/js/index.html - Ptolemy JavaScript documentation
• https://www.terraswarm.org/accessors/doc/jsdoc/ - TerraSwarm Accessors

How the Ptolemy JavaScript website is updated

We have a continuous integration (CI) build that updates https://chess.eecs.berkeley.edu/ptexternal/src/ptII/doc/codeDoc/js/index.html by checking the ptII svn repo for changes every 5 minutes. See http://terra.eecs.berkeley.edu:8080/job/ptIIci/

During the build, ant vendors-jsdoc-pull jsdoc is run. To see this step requires a Jenkins account with access to the ptIIci configuration. The settings are below:

The chess website is updated at the end of the build process by a Publish artifacts to SCP Repository post-build action.

To see this step requires a Jenkins account with access to the ptIIci configuration. The settings are below:

• "Publish artifacts to SCP Repository"
  • "SCP site": moog.eecs.berkeley.edu
    • "Files to upload"
    • "Source:" doc/codeDoc/**
    • "Destination:" cvswww/chess.eecs.berkeley.edu/ptexternal/src/ptII

How the TerraSwarm website is updated

We have a continuous integration (CI) build that updates https://www.terraswarm.org/accessors/doc/jsdoc/ by checking the accessors svn repo for changes every 5 minutes. See http://terra.eecs.berkeley.edu:8080/job/accessors/

During the build, ant build is run, which creates the *PtDoc.xml files and runs JSDoc. To see this step requires a Jenkins account with access to the accessors configuration.

The TerraSwarm website is updated by a "Send build artifacts over SSH" post-build step. The settings are below:

JSDoc Custom Tags

Unfortunately, the docs for adding custom tags to JSDoc are a bit sparse.

https://github.com/jsdoc3/jsdoc says: "Templates and Build Tools"

"The JSDoc community has created numerous templates and other tools to help you generate and customize your documentation. Here are just a few: Templates"

• "jaguarjs-jsdoc (example)"
  • See jaguarjs-jsdoc below
• "DocStrap"
  • See DocStrap below
• "jsdoc3Template (example)"
  • See jsdoc3Template below
• minami
  • See minami below
• http://usejsdoc.org/about-plugins.html Defines how to use plugins
  • http://usejsdoc.org/about-plugins.html#tag-definitions includes information about tag-definitions
• http://usejsdoc.org/plugins-markdown.html Discusses how to make it so MarkDown processing occurs in new tags.

JSDoc Custom Tag Plugin

Below is a description of what was necessary to set up the custom JSDoc Custom Tag Plugin for both the ptII and accessors repo.

There are two components: The plugin (covered here) and the JSDoc Custom Tag Fork (below).

Below are the steps that were done to set up the plugin in the ptII and accessor repos.

1. Edit jsdoc.json and add a plugins tag and value pair. The location of the accessorJSDocTags.js file is different for the ptII repo and the accessors repo
   1. For ptII, the plugin is at $PTII/doc/jsdoc/plugins/accessorJSDocTags.js, so $PTII/doc/jsdoc/jsdoc.json looks like:
      {
        ...
          "plugins": ["plugins/markdown", "doc/jsdoc/plugins/accessorJSDocTags"],
        ...
      }

      [$[Get Code]]
      The "plugins/markdown" enables the use of Markdown, see Using the Markdown plugin
   2. For the accessors, the plugin is at accessors/web/jsdoc/jsdoc.json, which contains:
      {
          ...
          "plugins": ["plugins/markdown", "jsdoc/plugins/accessorJSDocTags"]
          ...
      }

      [$[Get Code]]
2. The jsdoc.json file is read by jsdoc as follows:
   1. For ptII, after running ./configure, the ant file at $PTII/build.xml will contain:
       <target name="jsdoc"
                depends="vendors-jsdoc, jsdoc-getFromWiki"
                description="Run jsdoc to generate documentation for JavaScript files."
                >
          <echo>Invoke jsdoc to generate documentation for .js files.                            
          To set this up:                                                                        
             cd $PTII/vendors; git clone https://github.com/terraswarm/jsdoc.git                  
      
          $PTII/doc/jsdoc/topREADME.md will be used as the basis of the first page.              
      
          The output appears in doc/codeDoc/js/index.html                                        
          </echo>
          <exec executable="${jsdoc.home}/jsdoc">
            <arg value="--verbose" />
            <arg value="--recurse" />
            <arg value="-c" />
            <arg value="doc/jsdoc/jsdoc.json" />
            <arg value="-R" />
            <arg value="doc/jsdoc/topREADME.md" />
            <arg value="-d" />
            <arg value="doc/codeDoc/js" />
      
            <arg value="ptolemy/actor/lib/jjs"/>
            <arg value="ptolemy/actor/lib/vertx/demo"/>
            <arg value="org/terraswarm/accessor"/>
          </exec>
        </target>

      [$[Get Code]]
      1. The depends="vendors-jsdoc" is used to check out the fork of the JSDoc repo, more on this below.
      2. The jsdoc-getFromWiki gets a file from the TerraSwarm accessors wiki, see pmWiki to JSDoc
   2. For accessors, the ant file at accessors/web/build.xml contains:
         <target name="jsdoc"
                depends="vendors-jsdoc"
                description="Run jsdoc to generate documentation for JavaScript files."
                >
          <echo>Invoke jsdoc to generate documentation for .js files.                                                                          
          The output appears in doc/jsdoc/index.html                                                                                          
          </echo>
          <exec executable="${jsdoc.home}/jsdoc"
                timeout="10000"
                >
            <arg value="--configure" />
            <arg value="jsdoc/jsdoc.json" />
            <arg value="--destination" />
            <arg value="doc/jsdoc" />
            <arg value="--readme" />
            <arg value="README.md" />
            <arg value="--verbose" />
            <arg value="." />
          </exec>
        </target>

      [$[Get Code]]
   3. The depends="vendors-jsdoc" is used to check out the fork of the JSDoc repo, more on this below.
3. Create $PTII/doc/jsdoc/plugins/accessorJSDocTags.js or accessors/web/jsdoc/plugins/accessorJSDocTags.js:
   //Start of text from jsdoc/lib/jsdoc/tag/dictionary/definitions.js                                                                      
   function filepathMinusPrefix(filepath) {
       var sourcePaths = getSourcePaths();
       var commonPrefix = path.commonPrefix(sourcePaths);
       var result = '';
   
       if (filepath) {
           filepath = path.normalize(filepath);
           // always use forward slashes in the result                                                                                      
           result = (filepath + path.sep).replace(commonPrefix, '')
               .replace(/\\/g, '/');
       }
   
       if (result.length > 0 && result[result.length - 1] !== '/') {
           result += '/';
       }
   
       return result;
   }
   //end of text from jsdoc/lib/jsdoc/tag/dictionary/definitions.js
   
   exports.defineTags = function(dictionary) {
       dictionary.defineTag("accessor", {
           mustHaveValue: true,
           isNamespace: true, // Needed to get "accessor-" into the file name.                                                              
           onTagged: function(doclet, tag) {
               //console.log("accessorJSDocTags.js: accessor: " + doclet + " " + tag);                                                      
   
               // Start of text from jsdoc/lib/jsdoc/tag/dictionary/definitions.js                                                          
   
               // setDocletKindToTitle is not declared here, so we do what it says:                                                        
               //setDocletKindToTitle(doclet, tag);                                                                                        
               doclet.addTag( 'kind', tag.title );
   
               // setDocletNameToValue(doclet, tag);                                                                                        
               if (tag.value && tag.value.description) { // as in a long tag                                                                
                   doclet.addTag('name', tag.value.description);
               }
               else if (tag.text) { // or a short tag                                                                                      
                   doclet.addTag('name', tag.text);
               }
   
               if (!doclet.name) {
                   // setDocletNameToFilename(doclet, tag);                                                                                
                   var name = '';
   
                   if (doclet.meta.path) {
                       name = filepathMinusPrefix(doclet.meta.path);
                   }
                   name += doclet.meta.filename.replace(/\.js$/i, '');
   
                   doclet.name = name;
               }
               // Not sure if we need this:                                                                                                
               // in case the user wrote something like `/** @accessor  accessor:foo */`:                                                  
               //doclet.name = stripModuleNamespace(doclet.name);                    
   
               // setDocletTypeToValueType(doclet, tag);                                                                                    
               if (tag.value && tag.value.type) {
                   // Add the type names and other type properties (such as `optional`).                                                    
                   // Don't overwrite existing properties.                                                                                  
                   Object.keys(tag.value).forEach(function(prop) {
                       if ( !hasOwnProp.call(doclet, prop) ) {
                           doclet[prop] = tag.value[prop];
                       }
                   });
               }
   
               // End of text from jsdoc/lib/jsdoc/tag/dictionary/definitions.js                                                            
   
               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);
           }
       });
   };

   [$[Get Code]]

What the above code does is define tags that, when invoked, update an array that contains the instances of that tag.

Now the problem is how to use those tags.

JSDoc Custom Tag Fork

After an analysis of JSDoc Custom Tags documentation above, it seems that the best way to add our tags is to fork the git hub repo. So, we have https://github.com/terraswarm/jsdoc.

When ant jsdoc is run, the build.xml files can do a git clone and git pull of the fork of the JSDoc repo.

• If $PTII/vendors/jsdoc or accessors/web/vendors/jsdoc does not exist, then git clone https://github.com/terraswarm/jsdoc.git is invoked.
• To update the fork of the JSDoc repo, run ant vendors-jsdoc-pull
• To check out the repo by hand, use:
    cd vendors
    git clone https://github.com/terraswarm/jsdoc.git

  [$[Get Code]]

The following changes were made to the JSDoc repository.

• Added partial support for accessors.
  • lib/jsdoc/util/templateHelper.js
    •  exports.getMembers = function(data) {
           var members = {
      +        accessors: find( data, {kind: 'accessor'} ),
               classes: find( data, {kind: 'class'} ),
               externals: find( data, {kind: 'external'} ),
               events: find( data, {kind: 'event'} ),

      [$[Get Code]]
    • templates/default/publish.js
    • +    nav += buildMemberNav(members.accessors, 'Accessors', {}, linkto);
           nav += buildMemberNav(members.modules, 'Modules', {}, linkto);
           nav += buildMemberNav(members.externals, 'Externals', seen, linktoExternal);
           nav += buildMemberNav(members.classes, 'Classes', seen, linkto);

      [$[Get Code]]
• Now generating accessor-StockTick.html, but need to figure out links... This change had some debugging checked in that was later removed, below are the key changes:
  • templates/default/publish.js
    • 
           // once for all
           view.nav = buildNav(members);
      +    attachModuleSymbols( find({ longname: {left: 'accessor:'} }), members.accessors );
           attachModuleSymbols( find({ longname: {left: 'module:'} }), members.modules );
      
           // generate the pretty-printed source files first so other pages can link to them

      [$[Get Code]]
    •      indexUrl);
      
           // set up the lists that we'll use to generate pages
      +    var accessors = taffy(members.accessors);
           var classes = taffy(members.classes);
           var modules = taffy(members.modules);
           var namespaces = taffy(members.namespaces);

      [$[Get Code]]
    •      var interfaces = taffy(members.interfaces);
      
           Object.keys(helper.longnameToUrl).forEach(function(longname) {
      +        var myAccessors = helper.find(accessors, {longname: longname});
      +        if (myAccessors.length) {
      +            // FIXME: I don't understand the helper.longnameToUrl[longname] stuff, so just hardwire it.
      +            generate('Accessor: ' + myAccessors[0].name, myAccessors, "accessor-" + myAccessors[0].name + ".html");
      +        }
      +
               var myModules = helper.find(modules, {longname: longname});
               if (myModules.length) {
                   generate('Module: ' + myModules[0].name, myModules, helper.longnameToUrl[longname]);

      [$[Get Code]]
• To create files with the 'accessor-' prefix, the defineTag() in the plugin needs to set isNamespace and the containers variable needs to have 'accessor' added to it.
  • lib/jsdoc/util/templateHelper.js
    •  var ids = {};
      
       // each container gets its own html file
      -var containers = ['class', 'module', 'external', 'namespace', 'mixin', 'interface'];
      +var containers = ['accessor', 'class', 'module', 'external', 'namespace', 'mixin', 'interface'];
      
       var tutorials;
       

      [$[Get Code]]
    •  Object.keys(helper.longnameToUrl).forEach(function(longname) {
               var myAccessors = helper.find(accessors, {longname: longname});
               if (myAccessors.length) {
      -            // FIXME: I don't understand the helper.longnameToUrl[longname] stuff, so just hardwire it.
      -            generate('Accessor: ' + myAccessors[0].name, myAccessors, "accessor-" + myAccessors[0].name + ".html");
      +            generate('Accessor: ' + myAccessors[0].name, myAccessors, helper.longnameToUrl[longname]);
               }
      
               var myModules = helper.find(modules, {longname: longname});

      [$[Get Code]]
• Added support for accessors to handlers called by the parser visitors.

  • }
    
     function setCurrentModule(doclet) {
    -    if (doclet.kind === 'module') {
    +    if (doclet.kind === 'module' || doclet.kind === 'accessor') {
             currentModule = new CurrentModule(doclet);
         }
     }
     

    [$[Get Code]]
  •  function setDefaultScope(doclet) {
         // module doclets don't get a default scope
    -    if (!doclet.scope && doclet.kind !== 'module') {
    +    if (!doclet.scope && doclet.kind !== 'module' && doclet.kind !== 'accessor') {
             doclet.setScope(SCOPE_NAMES.GLOBAL);
         }
     }

    [$[Get Code]]
  • // b) the doclet represents a module
         // c) we're in a module that exports only this symbol
         if ( !newDoclet.memberof && newDoclet.kind !== 'module' &&
    -        (!currentModule || currentModule.longname !== newDoclet.name) ) {
    +         (!currentModule || currentModule.longname !== newDoclet.name)
    +         && newDoclet.kind !== 'accessor'
    +       ) {
             newDoclet.scope = SCOPE_NAMES.GLOBAL;
         }
     

    [$[Get Code]]

• https://github.com/terraswarm/jsdoc/commit/ba2307a2f22194926afb20a10f65099d09e1bcbd

  • At the end of the file:
    +
    +<?js if (data.inputs && data.inputs.length) { ?>
    +    <h5>Inputs:</h5>
    +    <?js= this.partial('params.tmpl', data.inputs) ?>
    +                                              <?js } ?>
    +
    +<?js if (data.outputs && data.outputs.length) { ?>
    +    <h5>Outputs:</h5>
    +    <?js= this.partial('params.tmpl', data.outputs) ?>
    +                                              <?js } ?>
    +
    +<?js if (data.parameters && data.parameters.length) { ?>
    +    <h5>Parameters:</h5>
    +    <?js= this.partial('params.tmpl', data.parameters) ?>
    +<?js } ?>

    [$[Get Code]]

JSDoc Custom Tag Notes

Notes about how the above procedure was determined.

Unable to parse a tag's type expression.

In the accessors repo, if web/jsdoc/plugins/accessorJSDocTags.js contains:

Then running ant jsdoc yields:

What's happening here is that we are getting an Object.

https://github.com/jsdoc3/jsdoc/issues/498 has a link to some code:

https://github.com/AnalyticalGraphicsInc/cesium/blob/92babfac/Tools/jsdoc3/plugins/customTags.js

https://github.com/AnalyticalGraphicsInc/cesium/blob/92babfac/Tools/jsdoc3/templates/default/tmpl/details.tmpl

So, one possibility would be to override the templates, see http://usejsdoc.org/about-configuring-default-template.html

https://code.google.com/p/jsdoc/source/browse/trunk/modules/jsdoc/tag/dictionary/definitions.js?r=19 has the following definition for param

Using that code results in something that at least does not cause errors. accessors/web/jsdoc/plugins/accessorJSDocTags.js now contains

The next step is to modify the template files

Modifying JSDoc's Template Files

Configuring JSDoc's default template states:

"Overriding the default template's layout file"

"The default template uses a file named layout.tmpl to specify the header and footer for each page in the generated documentation. In particular, this file defines which CSS and JavaScript files are loaded for each page. In JSDoc 3.3.0 and later, you can specify your own layout.tmpl file to use, which allows you to load your own custom CSS and JavaScript files in addition to, or instead of, the standard files."

"To use this feature, set the option templates.default.layoutFile to the path to your customized layout file. Relative paths are resolved against the path to the config.json file; the current working directory; and the JSDoc directory, in that order."

To do this, jsdoc.json would have:

The above works, but where to insert my changes? Ideally, I would like to define an option that would invoke some JavaScript that would process my custom arguments...

• https://github.com/danyg/jsdoc3Template -
• https://github.com/jsdoc3/jsdoc/blob/master/templates/README.md states that one needs to create a publish.js file that has a CommonJS publish() method.

Ideally, we would like to only copy a portion the default 1.1Mb of jsdoc/templates/default/

One idea is to define a method that would search our directory first.

Ant

Invoke jsdoc directly

1. Download jsdoc into vendors:
   cd $PTII/vendors
   git clone https://github.com/jsdoc3/jsdoc.git

   [$[Get Code]]
2. Create $PTII/b.xml:
   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <project basedir="." default="jsdocs">                                                                                            
     <property name="jsdoc.home" value="/Users/cxh/ptII/vendors/jsdoc" />
   
     <target name="jsdocs">
       <exec executable="${jsdoc.home}/jsdoc">
         <arg value="--verbose" />
         <arg value="--recurse" />
         <arg value="/Users/cxh/ptII/ptolemy/actor/lib/jjs"/>
       </exec>
     </target>
   
   </project>

   [$[Get Code]]
3. Run:
   ant -f b.xml

   [$[Get Code]]
4. See out/index.html

jsdoc3-ant-task

Summary: Do not use Instead, execute jsdoc directly as above Use https://github.com/jannon/jsdoc3-ant-task, it is for JSDoc 3

1. Download jsdoc3 and jsdoc3-ant-task:
   cd $PTII/vendors
   git clone https://github.com/jsdoc3/jsdoc
   git clone https://github.com/jannon/jsdoc3-ant-task

   [$[Get Code]]
2. Build jsdoc-ant-task:
   cd jsdoc-ant-task
   ant
   sudo cp /home/cxh/src/ptII/vendors/jsdoc3-ant-task/build/jar/jsdoc3-ant-task-1.0.jar /usr/local/apache-ant/lib

   [$[Get Code]]
3. Create b.xml
   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   <project basedir="." default="jsdocs">
     <property name="jsdoc.home" value="/home/cxh/src/ptII/vendors/>" />
   
     <path id="jsdoc3.classpath">
       <pathelement location="/home/cxh/src/ptII/vendors/jsdoc3-ant-task/build/jar/jsdoc3-ant-task-1.0.jar" />
       <pathelement location="/home/cxh/src/ptII/vendors/jsdoc3-ant-task/lib/jsdoc3/lib/js.jar" />
     </path>
   
     <target name="jsdocs">
       <taskdef name="jsdoc3" classname="net.jannon.ant.tasks.JsDoc3" classpathref="jsdoc3.classpath"/>
       <jsdoc3 jsdochome="${jsdoc.home}"
               file="ptolemy/actor/lib/jjs/basicFunctions.js"
               >
               <!-- arg line="-h true" / -->
       </jsdoc3>
     </target>
   
   </project>

   [$[Get Code]]
4. Run it:
   ant -f b.xml jsdocs
   

   [$[Get Code]]

However, I'm still not getting output?

It looks like this uses a custom version of jsdoc3 from jsdoc3-ant-task/lib/jsdoc3?

Also, Unknown command line option found: dirname=/home/admin/libs/jsdoc-master was generated, see https://github.com/jannon/jsdoc3-ant-task/issues/9 and https://github.com/jannon/jsdoc3-ant-task/issues/7

pmWiki to JSDoc

We have pmWiki pages at https://www.terraswarm.org/accessors/wiki/Version0/OptionalJavaScriptModules that we would like to show up at https://chess.eecs.berkeley.edu/ptexternal/src/ptII/doc/codeDoc/js/index.html

The way we do this is

1. Set up pmWiki so that we generate MarkDown text, see http://www.pmwiki.org/wiki/Cookbook/Markdown
   1. We use markdown because $PTII/doc/codeDoc/js/index.html includes $PTII/doc/jsdoc/topREADME.md, which is a MarkDown file
2. We download

https://www.terraswarm.org/accessors/wiki/Version0/OptionalJavaScriptModules?action=markdown using wget.

1. To do this, we need to save our cookies and use them with wget.
   1. Under Firefox, install https://addons.mozilla.org/en-us/firefox/addon/export-cookies/

Adding Hierarchy to JSDoc

Problem:

This page still doesn't show accessors in subdirectories:

https://chess.eecs.berkeley.edu/ptexternal/src/ptII/doc/codeDoc/js/index.html

Eventually, they will all be in subdirectories. All the more mature ones are in subdirectories REST, Camera, ImageFilters, etc)

Resources

• @namespace tag documentation (usejsdoc.org)
• How to use JSDoc3 to document nested namespaces (Stackoverflow)
  • We are not using JS Namespaces
• Find a way to show namespace paths #43 (github jsdoc3 issue)
  • Even if we were using namespaces, the tree view is not yet in JSDoc3

Ideas

• Create a separate page for each directory and then link to them.
  • This makes cross directory links tricky

Invoke JSDoc on itself

Running doit, we get Modules listed in the right with names like jsdoc/src/filter

Use the directory name in the accessor tag

One possibility is to have accessors/web/camera/Camera.js use

   *  @accessor camera/Camera  

instead of

   *  @accessor Camera

If this is done, then any accessors will be listed appropriately.

The nice thing about this is that it is similar to the @module tag in https://github.com/jsdoc3/jsdoc/blob/master/lib/jsdoc/src/filter.js vendors/jsdoc/lib/jsdoc/src/filter.js:

  @module jsdoc/src/filter 

Determine the root directory automatically.

If we did not want to go with using the directory in the @accessor tag, then in theory we could try to determine it. However, as we are running jsdoc in $PTII and it is possible that the accessors repo is checked out, how would we determine that org/terraswarm/accessor/accessors/web/cameras/Camera.js is in the "cameras/" directory?

• We could search for web, but that seems unportable
• We could use @namespace
• We could add another tag and use it as the directory name

Type Info as a separate Attribute

Edward wrote:

accessors/web/jsdoc/templates/ptdoc/publish.js is where we generate the output.

Here's a diff of that file

However, the output is not necessarily in the format we want. The type= elements look like:

For example, the type in ./image/MotionDetectorPtDoc.xml is an array:

We could eliminate the {names:[quot; and the trailing quot;])}, below is the complete function:

Now, these are the types:

• Back to JS