davidshimjs / jaguarjs-jsdoc Goto Github PK

It needs to be lighten up

Ever stumbled over something like this:

undefined:55
((__t=( filename ))==null?'':__t)+
        ^
ReferenceError: filename is not defined
    at eval (eval at <anonymous> (/usr/lib/node_modules/jsdoc/node_modules/underscore/underscore.js:1262:16), <anonymous>:55:9)
    at template (/usr/lib/node_modules/jsdoc/node_modules/underscore/underscore.js:1270:21)
    at exports.Template.partial (/usr/lib/node_modules/jsdoc/lib/jsdoc/template.js:62:29)
    at exports.Template.render (/usr/lib/node_modules/jsdoc/lib/jsdoc/template.js:81:24)
     .....

Well, then you've been using the -u switch, eh? Problem is that the template in tmpl/layout.tmpl uses the unbound javascript variable filename, which then, per underscore.js's template documentation, requires an object passed in with a property named filename as well.

You're doing this well for the other kinds of renderings, but not for the tutorials.

I fixed the problem locally by defining a property filename with value filename (the parameter for the function generateTutorial) on the tutorialData object, in publish.js around line 490.

I installed jsdoc via:

npm install jaguarjs-jsdoc

however when I tried to create a documentation with it I got:

Cannot find module 'underscore'
Cannot find module 'taffydb'

Running npm install underscore taffydb fixed the issue, but those dependencies should really be in the package.json.

A navigation bar menu of static class (tagged @Class and @static) don't expand.
This cause is a mismatch between the class name (ex. aaa.bbb.ccc#Ddd) and the file name (ex. aaa.bbb.ccc_Ddd) of the static class in main.js.
Modify following part of main.js (line 32-36):

// Show an item related a current documentation automatically
var filename = $('.page-title').data('filename').replace(/\.[a-z]+$/, '');
var $currentItem = $('.navigation .item[data-name*="' + filename + '"]:eq(0)');

if ($currentItem.length) {
...

to:

// Show an item related a current documentation automatically
var filename = $('.page-title').data('filename').replace(/\.[a-z]+$/, '');
var $linkItem = $('.navigation .item .title a[href="'+filename+'.html"]:eq(0)');
if ($linkItem.length) {
    $currentItem = $linkItem.parent().parent();
...

Great project!
In JSDoc it is meanwhile possible (#910) to suppress the date in the "generated by" comment. It would be great if that was available here as well.

I'd like to have a compiled todo list of all the @todo tags with their locations. I'd like the array available to the main page (Index.html). I've had much success customizing this template for my needs, but this is the only thing I haven't been able to figure out.

It would be great if you could provide tags for better referencing by package managers e.g. bower.

Standard @return tag gives incorrect output, eg.

• @returns {Number} Sum of a and b

gives:

"Returns:

of a and b "

http://usejsdoc.org/tags-returns.html

This issue was reported in jsdoc here: jsdoc/jsdoc#514; and solved with the following commit: jsdoc/jsdoc@f958ab0

However, the issue is still present in this template.

I applied the patch in the mentioned commit, to jaguarjs template, and the problem was gone (at least the one I was experiencing in my particular case).

undefined:25
if (item.members.length) {
^

TypeError: Cannot read property 'length' of undefined
at eval (eval at _.template (C:\DATA\JSdoc\node_modules\underscore\underscore.js:1454:20), :25:30)
at Array.forEach ()
at exports.Template.eval (eval at _.template (C:\DATA\JSdoc\node_modules\underscore\underscore.js:1454:20), :13:14)
at exports.Template.template (C:\DATA\JSdoc\node_modules\underscore\underscore.js:1461:21)
at exports.Template.partial (C:\DATA\JSdoc\node_modules\jsdoc\lib\jsdoc\template.js:55:29)
at exports.Template.eval (eval at _.template (C:\DATA\JSdoc\node_modules\underscore\underscore.js:1454:20), :54:14)
at exports.Template.template (C:\DATA\JSdoc\node_modules\underscore\underscore.js:1461:21)
at exports.Template.partial (C:\DATA\JSdoc\node_modules\jsdoc\lib\jsdoc\template.js:55:29)
at exports.Template.render (C:\DATA\JSdoc\node_modules\jsdoc\lib\jsdoc\template.js:74:24)
at generate (C:\DATA\JSdoc\node_modules\jaguarjs-jsdoc\publish.js:128:21)
at Object.exports.publish (C:\DATA\JSdoc\node_modules\jaguarjs-jsdoc\publish.js:471:35)
at Object.module.exports.cli.generateDocs (C:\DATA\JSdoc\node_modules\jsdoc\cli.js:448:35)
at Object.module.exports.cli.processParseResults (C:\DATA\JSdoc\node_modules\jsdoc\cli.js:399:20)
at module.exports.cli.main (C:\DATA\JSdoc\node_modules\jsdoc\cli.js:240:14)
at Object.module.exports.cli.runCommand (C:\DATA\JSdoc\node_modules\jsdoc\cli.js:189:5)
at C:\DATA\JSdoc\node_modules\jsdoc\jsdoc.js:105:9

When define a namespace twice (in one same file or different files), it generate like this:

@typedefs or @global are placed in global.html. But there is no link to it from the nav pane.

If I have a CommonJS style module exporting different methods, it does not appear in the compiled documentation if I use the @module tag along with @function tags for each method.

A Class that showed at current page will be shown by scrolling instead of changing order at navigation area.

I noticed that first word of return description gets missed in the output.

Example from JaguarJS (collie.util.getBoundaryToPoints):

/**
 * ...
 * @return {Array} points [[left, top], [right, top], [right, bottom], [left, bottom]]
 */

Output:

Returns:
[[left, top], [right, top], [right, bottom], [left, bottom]] 

Word "points" is missing.

For complex return values it creates a proper output, but nor for a simple case.

Thanks for your template!

I think I found a bug. Interfaces (tag @interface) are missing in the output documentation.

Example:

/**
 * @interface
 */
myInterface = {
    /**
     * Foo.
     */
    foo : function() {}
}

The default jsdoc template does output it (on the right side, part with "Interfaces" title). But jaguarjs-jsdoc seems to omit it completely.

I would expect that html tags are displayed not rendered. It works with baseline and ink templates, but I prefer yours. How can I achieve baseline style?

Left sidebar menu don't expend upon clicking class title. Amend main.js to fix

// Toggle when click an item element
$('.navigation').on('click', '.title', function (e) {
  e.preventDefault();
    $(this).parent().find('.itemMembers').toggle();
});

I'm trying to set up jsdoc3 with jaguarjs, and it seems to not want to listen to me. At all.

I simply cloned https://github.com/davidshimjs/jaguarjs-jsdoc into the dir I'm working in, and created a config file in the same dir:

{
  "plugins": [ "plugins/markdown" ],
  "markdown": {
    "parser": "gfm"
  },
  "opts": {
    "template" : "jaguarjs-jsdoc",
    "recurse": true,
    "tutorials": "./tutorials",
    "destination": "./documentation"
  }
}

Then ran jsdoc: jsdoc -c jsdoc.json src/*

Just to get:

rwoverdijk@battlestation ~/projects/nodejs/islnew/tier3/assets/scripts/islive.io (master)
$ jsdoc -c jsdoc.json src/*

undefined:55
((__t=( filename ))==null?'':__t)+
        ^
ReferenceError: filename is not defined
    at eval (eval at <anonymous> (/usr/local/lib/node_modules/jsdoc/node_modules/underscore/underscore.js:1262:16), <anonymous>:55:9)
    at template (/usr/local/lib/node_modules/jsdoc/node_modules/underscore/underscore.js:1270:21)
    at exports.Template.partial (/usr/local/lib/node_modules/jsdoc/lib/jsdoc/template.js:62:29)
    at exports.Template.render (/usr/local/lib/node_modules/jsdoc/lib/jsdoc/template.js:81:24)
    at generateTutorial (/Users/rwoverdijk/projects/nodejs/islnew/tier3/assets/scripts/islive.io/jaguarjs-jsdoc/publish.js:501:25)
    at /Users/rwoverdijk/projects/nodejs/islnew/tier3/assets/scripts/islive.io/jaguarjs-jsdoc/publish.js:512:13
    at Array.forEach (native)
    at saveChildren (/Users/rwoverdijk/projects/nodejs/islnew/tier3/assets/scripts/islive.io/jaguarjs-jsdoc/publish.js:511:23)
    at Object.exports.publish (/Users/rwoverdijk/projects/nodejs/islnew/tier3/assets/scripts/islive.io/jaguarjs-jsdoc/publish.js:516:5)
    at Object.module.exports.cli.generateDocs (/usr/local/lib/node_modules/jsdoc/cli.js:412:18)

I'm using version:

rwoverdijk@battlestation ~/projects/nodejs/islnew/tier3/assets/scripts/islive.io (master)
$ jsdoc -v
JSDoc 3.3.0-alpha9 (Sat, 28 Jun 2014 15:26:03 GMT)

I also tried master, with no success.

JSDoc 3.3.0 replaces < characters with < in its default documentation process. jaguarjs-jsdoc does not, causing issues with HTML parsing for the browser. Here's an example of documentation that breaks it

/**
 * @example
 * for(var i = 0; i<n; i++) {}
 **/
 function a(){};

JSDoc uses this code to escape the HTML: https://github.com/jsdoc3/jsdoc/blob/f55feb1a0e5cf8bd3ffa8e94a6ec6c66e21378de/plugins/escapeHtml.js

Here is my environment and the issue details

2 info using [email protected]
3 info using [email protected]

> [email protected] docs /mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3
> jsdoc -c ./gulp/util/jsdoc.conf.json -R README.md

fs.js:1919
  binding.copyFile(src, dest, flags);
          ^

Error: EISDIR: illegal operation on a directory, copyfile '/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jaguarjs-jsdoc/static/fonts/glyphicons-halflings-regular.eot' -> 'docs/fonts'
    at Object.fs.copyFileSync (fs.js:1919:11)
    at /mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jaguarjs-jsdoc/publish.js:347:12
    at Array.forEach (<anonymous>)
    at Object.exports.publish (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jaguarjs-jsdoc/publish.js:344:17)
    at Object.module.exports.cli.generateDocs (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/cli.js:430:39)
    at Object.module.exports.cli.processParseResults (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/cli.js:383:20)
    at module.exports.cli.main (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/cli.js:227:14)
    at Object.module.exports.cli.runCommand (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/cli.js:180:5)
    at /mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/jsdoc.js:103:9
    at Object.<anonymous> (/mnt/c/Users/Administrator/Workspace/github_pkgs/pixi.js-3/node_modules/jsdoc/jsdoc.js:104:3)
    at Module._compile (module.js:624:30)
    at Object.Module._extensions..js (module.js:635:10)
    at Module.load (module.js:545:32)
    at tryModuleLoad (module.js:508:12)
    at Function.Module._load (module.js:500:3)
    at Function.Module.runMain (module.js:665:10)

Is there a way to suppress the output of div.tag-source ?

I'm using jaguarjs-jsdoc via grunt-jsdoc, and the tag source is showing the file path all the way down to the root of my OS, eg:

<div class="tag-source">/Volumes/VRMiniBackup/Backups/Web/Bitbucket/ob/wp-content/themes/sitename/resources/dev/scripts/sitename.js, line 2787</div>

This makes the div.tag-source overlap the adjacent documentation at all but the widest viewport widths.

Thanks.