yui / yuidoc

YUI Javascript Documentation Tool

YUIDoc

YUI's JavaScript Documentation engine.

Overview

YUIDoc is a Node.js application used at build time to generate API documentation for JavaScript code. YUIDoc is comment-driven and supports a wide range of JavaScript coding styles. The output of YUIDoc is API documentation formatted as a set of HTML pages including information about methods, properties, custom events and inheritance for JavaScript objects.

YUIDoc was originally written for the YUI Project; it uses YUI JavaScript and CSS in the generated files and it supports common YUI conventions like Custom Events. That said, it can be used easily and productively on non-YUI code.

Installation

npm install -g yuidocjs

Documentation

• User Guides
• Change Logs
• API Docs
• Mailing List

Contributing

Please see the CONTRIBUTING.md.

License

This software is free to use under the Yahoo Inc. BSD license. See the LICENSE file for license text and copyright information.

yuidoc's Issues

Cross-referencing Modules and Classes

Unable to generate links to other modules and classes using {{#crossLink Foo}} (where Foo is a module or class), as documented on http://yui.github.com/yuidoc/syntax/index.html#cross-referencing-modules-and-classes.

SyntaxError: Unexpected token ?

Fresh install of YUIDoc, tried running it for the first time and get this error.

Wasn't sure if I should file an issue but there's not much information on how to handle errors so if I'm missing something let me know.

error: -------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: -------------------------------------------------------------------------
error:
SyntaxError: Unexpected token ?
    at Object.parse (native)
    at Object.getJSON (C:\Users\EricT\AppData\Roaming\npm\node_modules\yuidocjs\
lib\files.js:376:21)
    at C:\Users\EricT\AppData\Roaming\npm\node_modules\yuidocjs\lib\utils.js:248
:39
    at Array.forEach (native)
    at [object Object].getProjectData (C:\Users\EricT\AppData\Roaming\npm\node_m
odules\yuidocjs\lib\utils.js:237:10)
    at Object.init (C:\Users\EricT\AppData\Roaming\npm\node_modules\yuidocjs\lib
\project.js:19:29)
    at Object.<anonymous> (C:\Users\EricT\AppData\Roaming\npm\node_modules\yuido
cjs\lib\cli.js:23:21)
    at Module._compile (module.js:446:26)
    at Object..js (module.js:464:10)
    at Module.load (module.js:353:31)
error: -------------------------------------------------------------------------
error: Node.js version: v0.6.18
error: YUI version: 3.5.1
error: YUIDoc version: 0.3.9
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: -------------------------------------------------------------------------

Here's my yuidoc.json file

{
    “name” : “Test”,
    “description” : “Testing yuidoc”,
    “version” : “1”,
    “url” : “”,
    “options” : {
        “outdir” : “../docs”,
        "theme" : "simple"
    }
}

YUIDoc does not follow symlinks?

Hey all,

I was all ready to test out yuidoc on my project, but the script failed with the following error:

...
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error: Can not find directory: node_modules/amino
...

In this project, amino was 'installed' via npm link, so it is a symlink to /usr/local/lib/node_modules. I can get around this short-coming by running yuidoc in a temp directory where all the dependencies have been hard-installed. I would prefer to be able to run the utility from my working project root though.

Optional nested params are not marked as such

/**
 * @event change
 * @param ev {EventFacade} containing:
 * @param [ev.name] {String} Name of the field changed
*/

name is not getting marked as optional in the output.

Neither do these:

• @param ev.[name] {String} Name of the field changed
• @param {String} [ev.name] Name of the field changed

Non-nested optional arguments work just fine.
Starting [email protected] using [email protected] with [email protected]

#crosslink doesn't work on attributes or events

I wanted to have a reference to an attribute and it didn't work. I changed, for the sake of trying, to a method in the same class and it worked fine. Then I wondered about events and tried to reference an event. Doesn't work either.

Also, there is an issue with this. Though methods and properties cannot have the same name, events and attributes are in different namespaces and they may have the same names as class members. For example, Y.Model has both load and save methods and events (admittedly, the events should have been named loaded and saved, since they happen after the fact, they cannot be listened to and halted if you wanted to prevent them from happening). The syntax does not allow to discriminate amongst them should there be an ambiguity.

If it can't be fixed, please document it.

Thanks

Is it possible to indicate that an attribute is required or optional?

yuidoc.json does not work for js files in project root

It seems like if I use yuidoc.json paths option, there is no way to generate doc for js files in the current project root.

For example, this is my project structure:

• node_modules/
• test/
• doc/
• index.js
• yuidoc.json
  ...

this is my yuidoc.json:

{
"name": "blah",
"description": "blah module",
"version": "0.0.2",
"url": "http://www.blahisgood",
"options": {
"linkNatives": "true",
"attributesEmit": "false",
"selleck": "false",
"ignorePaths": ["node_modules", "test"],
"paths": "*",
"outdir": "./docs"
}
}

The doc for index.js is not generated. I also tried ".", "./*.js" for paths and they did not work either.

I think the problem is that validatePaths function in lib/util.js calls getDirs('.'), which only recursively gets all the subdirectories under '.', but not including '.'.

If I use command line "yuidoc . -x node_modules,test", it works as expected, only doc for index.js is generated.

Add syntax to specify information about parameters

For example, to indicate that an element of a configuration object is required - from

TypeError when using a custom theme

When I try to load a page with yuidoc running as a server I get the following error:

TypeError: Cannot read property 'name' of undefined
    at /usr/local/lib/node_modules/yuidocjs/lib/builder.js:859:44
    at [object Object].prepare (/usr/local/lib/node_modules/yuidocjs/lib/utils.js:216:5)
    at Object.renderClass (/usr/local/lib/node_modules/yuidocjs/lib/builder.js:851:15)
    at Object.clazz (/usr/local/lib/node_modules/yuidocjs/lib/server.js:110:28)
    at /usr/local/lib/node_modules/yuidocjs/lib/server.js:52:24
    at callbacks (/usr/local/lib/node_modules/yuidocjs/node_modules/express/lib/router/index.js:272:11)
    at /usr/local/lib/node_modules/yuidocjs/lib/server.js:31:13
    at callbacks (/usr/local/lib/node_modules/yuidocjs/node_modules/express/lib/router/index.js:272:11)
    at param (/usr/local/lib/node_modules/yuidocjs/node_modules/express/lib/router/index.js:246:11)
    at param (/usr/local/lib/node_modules/yuidocjs/node_modules/express/lib/router/index.js:243:11)

I'm starting yuidoc as follows:

yuidoc --themedir . --server 5000 .

In my local dir I have a directory named themes and within that I have default which contains the Handlebars templates.

An uncaught YUIDoc Error

Before it works well, but suddenly appeared such error as below.

error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error:
TypeError: Cannot set property 'module' of undefined
at [object Object]. (D:\nodejs\node_modules\yuidocjs\lib\docparser.js:479:29)
at [object Object]. (D:\nodejs\node_modules\yuidocjs\lib\docparser.js:1211:40)
at Array.forEach (native)
at Function. (D:\nodejs\node_modules\yuidocjs\node_modules\yui\yui-nodejs\yui-nodejs.js:2265:20)
at f (D:\nodejs\node_modules\yuidocjs\node_modules\yui\oop/oop-min.js:7:220)

at [object Object].each (D:\nodejs\node_modules\yuidocjs\node_modules\yui\oop/oop-min.js:7:1206)
at [object Object].processblock (D:\nodejs\node_modules\yuidocjs\lib\docparser.js:1183:15)
at [object Object].<anonymous> (D:\nodejs\node_modules\yuidocjs\lib\docparser.js:1267:26)
at Array.forEach (native)
at Function.<anonymous> (D:\nodejs\node_modules\yuidocjs\node_modules\yui\yui-nodejs\yui-nodejs.js:2265:20)

error: -------------------------------------------------------------------------

error: Node.js version: v0.6.1
error: YUI version: 3.5.1
error: YUIDoc version: 0.3.5
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: -------------------------------------------------------------------------

Overridden method is shown twice

The method and params are identical in both files. I tried with the same description and with different descriptions. Somewhere, I saw it render it once and say "defined in X but overridden in Y", but it's not working for my code.

@requires does not work

YUIDoc 0.3.19，Use @requires in a @module,but the doc does not show the requires module name!

How to mention default value for optional parameters?

How can I mention default value for optional parameters?

Wrapping a param in square brackets marks it optional. But how to mention its default value? Ideally, all optional parameters should have a default value. So instead of the square brackets, the syntax should have been:
@param {Number} num=10
Assigning a value to the variable automatically marks its optional with default value of 10.

YUIDoc Page Points to wrong URL for Download

The YUIDoc page at:
http://developer.yahoo.com/yui/yuidoc/

point to:
http://yuilibrary.com/downloads/

in order to download yuidoc.

It should point to:
https://github.com/yui/yuidoc

'Maximum call stack size exceeded' error

Previously got an error building docs (Object e {EventFacade} Event object has no method 'foreach'), so I updated to 0.3.14 and now I get this error when building (not parsing).

Any tips on how to dig for more information?

info: (builder): Rendering and writing 168 class pages.
error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error: Maximum call stack size exceeded
error: --------------------------------------------------------------------------
error: Node.js version: v0.6.17
error: YUI version: 3.5.1
error: YUIDoc version: 0.3.14
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: --------------------------------------------------------------------------

Crossover between modules

I'm seeing classes from one module being displayed as part of a different module. I'll send you the tarball.

yuidoc . --theme simple doesn't work

I'm trying to compile with the "simple" theme.
But when I type in yuidoc . -T simple, I get this error.

error: -------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error:
ReferenceError: path is not defined
    at YUI.add.Y.Options (C:\Users\d\AppData\Roaming\npm\node_modules\yuidocjs
\lib\options.js:113:40)
    at Object.<anonymous> (C:\Users\d\AppData\Roaming\npm\node_modules\yuidocj
s\lib\cli.js:17:17)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.runMain (module.js:487:10)
    at process.startup.processNextTick.process._tickCallback (node.js:244:9)
error: -------------------------------------------------------------------------
-
error: Node.js version: v0.8.1
error: YUI version: 3.6.0pr3
error: YUIDoc version: 0.3.16
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: --------------------------------------------------------------------------

Style improvement, ellipsis on too long class names

add

.apis a {
  text-overflow: ellipsis;
  overflow: hidden;
}

and a title attribute with the complete name to the links and you have no more overflow.

yuidocjs output only has -moz styles

So it doesn't look very nice in Chrome or Safari.

Extends self..

When I extend the class itself(of cause, it was mistake),
yuidoc crashed with following message, instead of tell me it extends self(kindly).

error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error: Maximum call stack size exceeded
error: --------------------------------------------------------------------------
error: Node.js version: v0.6.12
error: YUI version: 3.6.0pr3
error: YUIDoc version: 0.3.15
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: --------------------------------------------------------------------------

Support multiple items in options.external

I would like to link to both the yui docs and gallery module docs

Just upgraded to YUIDoc 0.3.2, getting uncaught exception

Hi. I'm running Windows 7 x64.

I originally had a version of YUIDoc installed, I think it was 0.2.5 or something in that range. I don't know how to check anymore.

I saw that there was a new version of YUIDoc released so I went ahead and did the following command:

npm install -g yuidocjs

This completed.

Then I ran:

yuidoc . --server

And all of a sudden I get this error:

Thinking that maybe I should do a fresh install, I ran the following commands:

npm uninstall -g yuidocjs
npm install -g yuidocjs

These completed, issue still not fixed.

I even did the uninstall and reinstall while running cmd.exe as Administrator.

URLs with special characters

If you define (for example) an event like this:

/**
 * Some cool bubbling event.
 * @event MyClass:myEvent
 */

Then in the index it will point to #event_MyClass:myEvent, but that doesn't work. I haven't investigated on why the router does not work.

Uncaught Error Rendering Class Pages

I keep seeing this error: "Object [force] {Boolean} Disregard safety measures? has no method 'forEach'" when rendering class pages. The issue URL at the bottom probably needs to be updated as well.

error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error: 
TypeError: Object [force] {Boolean} Disregard safety measures? has no method 'forEach'
    at /usr/local/lib/node_modules/yuidocjs/lib/builder.js:949:42
    at Array.forEach (native)
    at /usr/local/lib/node_modules/yuidocjs/lib/builder.js:943:28
    at [object Object].prepare (/usr/local/lib/node_modules/yuidocjs/lib/utils.js:216:5)
    at Object.renderClass (/usr/local/lib/node_modules/yuidocjs/lib/builder.js:867:15)
    at [object Object].<anonymous> (/usr/local/lib/node_modules/yuidocjs/lib/builder.js:1146:22)
    at Function.each (/usr/local/lib/node_modules/yuidocjs/node_modules/yui/yui-nodejs/yui-nodejs.js:3041:16)
    at f (/usr/local/lib/node_modules/yuidocjs/node_modules/yui/oop/oop-min.js:7:296)
    at [object Object].each (/usr/local/lib/node_modules/yuidocjs/node_modules/yui/oop/oop-min.js:7:1206)
    at Object.writeClasses (/usr/local/lib/node_modules/yuidocjs/lib/builder.js:1144:15)
error: --------------------------------------------------------------------------
error: Node.js version: v0.6.18
error: YUI version: 3.5.1
error: YUIDoc version: 0.2.44
error: Please file all tickets here: http://github.com/davglass/yuidocjs/issues
error: --------------------------------------------------------------------------

option.external.data not working

With this configuration, extends are not linked. If I remove the jafl.github.com link, then extends are linked.

"options":
{
    "external":
    {
        "data":
        [
            "http://jafl.github.com/yui3-gallery/yuidoc/data.json",
            "http://yuilibrary.com/yui/docs/api/data.json"
        ]
    }
}

Should not encode full path to source files in yuidoc/files

I just moved to a different computer under a different user name, and everything in the files directory now has a different name. All the existing links will be broken.

Plus, security generally recommends not exposing full paths to anything :)

@main isn't documented

@main is referenced several times on http://yui.github.com/yuidoc/syntax/ but all the links go to http://yui.github.com/yuidoc/syntax/index.html#main which doesn't actually exist.

@main is used in YUI code, I just can't tell exactly what it's used for.

Yuidoc wont run, it appears to not be loading modules properly

I'm trying to run yuidoc on my windows 7 laptop. Every time I run it I just get this error. I just installed yuidoc with npm install -g yuidocjs. I tried uninstalling and reinstalling but I havent had any success. I looked inside index.js the paths and everything getting set seem correct but I'm pretty certain none of the module scripts are getting run.

PS C:\dev\workspace\isis> yuidoc .
error: --------------------------------------------------------------------------
error: An uncaught YUIDoc error has occurred, stack trace given below
error: --------------------------------------------------------------------------
error:
TypeError: Cannot call method 'getJSON' of undefined
at Object. (C:\Users\lmproto\AppData\Roaming\npm\node_modules\yuidocjs\lib\index.js:96:25)
at Module._compile (module.js:444:26)
at Object..js (module.js:462:10)
at Module.load (module.js:351:31)
at Function._load (module.js:310:12)
at Module.require (module.js:357:17)
at require (module.js:373:17)
at Object. (C:\Users\lmproto\AppData\Roaming\npm\node_modules\yuidocjs\lib\cli.js:14:9)
at Module._compile (module.js:444:26)
at Object..js (module.js:462:10)
error: --------------------------------------------------------------------------
error: Node.js version: v0.6.9
error: YUI version: 3.5.1
error: YUIDoc version: 0.3.14
error: Please file all tickets here: http://github.com/yui/yuidoc/issues
error: --------------------------------------------------------------------------

any operation prompt operation not permitted

C:\Users\Administrator>yuidoc --server 8000
info: (yuidoc): Starting [email protected] using [email protected] with [email protected]
info: (yuidoc): Scanning for yuidoc.json file.

error: -------------------------------------------------------------------------

error: An uncaught YUIDoc error has occurred, stack trace given below

error: -------------------------------------------------------------------------

error:
Error: EPERM, operation not permitted 'C:\Users\Administrator\AppData\Local\Appl
ication Data'
at Object.fs.readdirSync (fs.js:500:18)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:236:19)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:263:27)
at Array.forEach (native)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:237:10)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:263:27)
at Array.forEach (native)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:237:10)
at YUI.add.getProjectData (C:\Program Files\nodejs\node_modules\yuidocjs\lib
\utils.js:263:27)
at Array.forEach (native)

Document stand-alone functions

This is probably a simple question

Taking an AMD approach, how do you properly document a stand-alone function?
I've been looking at the docs and examples, but I wasn't able to find anything related…

Example to help clarify my problem:

/**
 * bind
 *
 * @version 0.0.1
 * @module function
 */
define(function () {

    /**
     * binds a function to a given object (context)
     *
     * @function
     * @param {Function} fn Function to be bound
     * @param {Object} context Object that will serve as context
     * @return {Function} bound function
     */
    return function (fn, context) { /* code */ }

});

This is an AMD module that returns a simple bind function, but because it's not a class and it's not exactly a constructor, i totally fail to make that function's documentation appear in the generated docs, at least correctly.

A module can not be two parents module's submodule

The module tag is grate!
But I am confuse why it can not makes a many-to-many relationship?If the App design with MVC,and the M,V,C is in different files.
Such as,module A includes M1,V1,C1,and module B includes M1,V2,C2.
For now,the M1 module can only be module A's or B's submodule.

And also,In App.js I have a module like this:

/**

• @module App
  /
  /*
• @Class App
• @static
  /
  var App = {};
  
  The doc will show me the wrong "Defined in: src/app/notApp.js:12" dir.
  But if I do it like this:
  
/*
• @module
• @submodule App
• @main App
  /
  /*
• @class App
• @static
*/
var App = {};

  The doc will be right.
  But both make the other js files in the same dir are belong to module App.

Actually,I hope the module tag just mean to be a group,just for relationship.

Some HTML tags not working in all comment blocks

HTML Tags –like <b> <br/>– are working for @class blocks, but not for other blocks (like properties and methods), where <p> or <strong> should be used instead.
<code> seems to work anywhere though.

I’m using 0.3.5 on Mac OS.

@async is not rendered for @method

@return tag supports complex object

If a return value is an object with a complex structure, you can nest @param tags underneath the @return value.

Check for package.json in addition to yuidoc.json.

For node.js modules, the yuidoc.json semantics look strikingly familiar to package.json:

{
    "name": "The Foo API",
    "description": "The Foo API: a library for doing X, Y, and Z",
    "version": "1.2.1",
    "url": "http://example.com/",
}

All of these properties are valid in package.json files and in fact are semantically the exact same values (if you are generating docs for the same code-level).

I propose that yuidocs could look for a package.json file and extract the following properties from it:

• name
• description
• version
• url
• logo

For options I propose those be specified on a yuidoc property in package.json. So, a sample package.json that yuidoc could parse might look like:

{
    "name" : "mkdirp",
    "description" : "Recursively mkdir, like `mkdir -p`",
    "version" : "0.3.2",
    "author" : "James Halliday <[email protected]> (http://substack.net)",
    "main" : "./index",
    "keywords" : [
        "mkdir",
        "directory"
    ],
    "repository" : {
        "type" : "git",
        "url" : "http://github.com/substack/node-mkdirp.git"
    },
    "scripts" : {
        "test" : "tap test/*.js"
    },
    "devDependencies" : {
        "tap" : "~0.2.4"
    },
    "license" : "MIT/X11",
    "engines": { "node": "*" },
    "yuidoc": {
      "linkNatives": "true",
      "paths": "index.js",
      "outdir": "docs"
    }
}

If you wanted to future-proof this for additional config, you could amend the yuidoc property to look more like:

...
    "yuidoc": {
      "url": "http://someurl",
      "options": {
         "linkNatives": "true"
      }  
    }
...

In this case the yuidoc.url would override top level url property (if one existed).

The net benefit of parsing package.json would be one less config file in you project root, less redundancy of name/version/description (you don't have to remember to update it in so many places), and a little more friendliness with node.js (and indeed other communities that use package.json, like jQuery plugins are slated to do).

Support @example as a class level element

I have been working with yuidoc with the default theme, and I had used @example at the class level to illustrate usage.

It seemed a common pattern, at least there were syntax highlighted examples with many other examples.

Instead, it just silently broke my formatting.

Should @example be supported? It seems so.

yuidoc.json ignorePaths option does not work

It seems like there is a bug in validatePaths function in lib/util.js:

if (ignore) {
if (!(ignore instanceof Array)) {
ignore = [ignore];
}
var p = [];
paths.forEach(function(v) {
ignore.forEach(function(i) {
if (v.indexOf(i) === -1) {
p.push(v);
}
});
});
paths = p;
}

So, if ignore array contains at least two paths, for example:
paths = ['a', 'b', 'c']
ignore = ['a', 'b']
When you use the two forEach to check each element in paths, say, you check 'a' from paths against 'a', 'b' in ignore, since 'a'.indexOf('b') will give you -1, 'a' will be added to the final paths array instead of getting filters.

Instead, should do something like this:

if (ignore) {
if (!(ignore instanceof Array)) {
ignore = [ignore];
}
var p = [];
var shouldIgnore = false;
paths.forEach(function(v) {
shouldIgnore = false;
ignore.forEach(function(i) {
if (!shouldIgnore && v.indexOf(i) !== -1) {
shouldIgnore = true;
}
});
if (!shouldIgnore) {
p.push(v);
}
});
paths = p;
}

The doc got the wrong "Define in:"

In App.js I have a module like this:

/**
 * @module App
 */
/**
 * @class App
 * @static
 */
var App = {};

The doc will show me the wrong "Defined in: src/app/other.js:12" dir. But if I do it like this:

/**
 * @module 
 * @submodule App
 * @main App
 */
/**
 * @class App
 * @static
 */
var App = {};

The doc shows right."Defined in: src/app/App.js:1"
But both make the other js files in the same dir are belong to module App,that confuse me.

params (instead of param) typo causes error

I realize it was my mistake. I accidentally typed "@params" instead of "@param," but I thought you might like to see the error anyway.

TypeError: Object {Object} [params.captions] See VM.Asset.Media.Captions constructor for options. has no method 'push'
at [object Object]. (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\lib\docparser.js:344:18)
at [object Object]. (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\lib\docparser.js:1213:40)
at Array.forEach (native)
at Function. (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\node_modules\yui\yui-nodejs\yui-nodejs.js:2265:20)
at f (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\node_modules\yui\oop/oop-min.js:7:220)
at [object Object].each (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\node_modules\yui\oop/oop-min.js:7:1206)
at [object Object].processblock (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\lib\docparser.js:1185:15)
at [object Object]. (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\lib\docparser.js:1269:26)
at Array.forEach (native)
at Function. (C:\Users\Bobby\AppData\Roaming\npm\node_modules\yuidocjs\node_modules\yui\yui-nodejs\yui-nodejs.js:2265:20)

Callback tag/type

It would be nice to be able to document function callbacks and reference these from functions like this.

/**
 * My function.
 *
 * @method myMethod
 * @param {MyCallback} callback A callback to be executed.
 */

/**
 * A callback.
 *
 * @callback MyCallback
 * @param {String} myString Some string.
 */

Tag to signal a class is not meant to be instantiated directly

I have a class that can be instantiated though it shouldn't be done directly but via a factory. Neither the @constructor nor the @static secondary tags indicate this.

It might be better if an extra tag could be used to indicate this, possibly pointing at the factory object as its argument.

@viaFactory FactoryClass

Enhancement: Add tooltips to the index view.

When browsing the index page of a class and trying to find a particular method when there are many methods to look through, it can become frustrating to click on a method, wait for the method's page to load, read the method's description, decide that this isn't the method I'm looking for, then navigate back to the index.

I feel it would be nice and helpful to provide tooltips on the index page so a quick mouse over would reveal the desired information. It would simplify and speed up the process of browsing through a large API.

Inheritance missing when @module and @class are in the same block

If I do this:

/**

• @module gallery-datasource-async-function
• @Class AsyncFunction
• @namespace DataSource
• @extends DataSource.Local
• @constructor
• @param config {Object}
  */

Then the result does not show "Extends DataSource.Local"

But if I do this:

/**

• @module gallery-datasource-async-function
  */

/**

• @Class AsyncFunction
• @namespace DataSource
• @extends DataSource.Local
• @constructor
• @param config {Object}
  */

then the base class is shown.

Output directory is entirely obliterated, including a .git dir

I am exporting into a gh-pages directory, which has a .git path. Unfortunately, when I export to that directory the entire directory is removed, including .git.

I have this wrapped, but it could be easier to export directly to a git managed directory (specifically in a gh-pages branch).

Request: Bold/Highlight methods or attributes that are specific only to this class

I think it would be really useful to be able to bold or highlight the items in the YUIDoc "Index" tab that are specific only to this class.

What I mean by specific to this class is:

• Method or attribute does not exist in any superclasses.
• Method or attribute overrides the one in the superclass.

This way when I extend something with a lot of methods/attributes, like Y.Widget, someone reading the API doc can easily see how this subclass is different from the vanilla Widget class.

Arguments after --server fail

Extending classes sometimes results in duplicate method descriptions instead of overwritten ones.

See simple reproducible case here:
http://www.wei-wang.com/yui/yuidoc_override_issue/

Look at the subWidget. It has two myMethod classes when it should just have one that is labelled as an override.

Submodules with the same name

The following code will result only in
m_1 holding s_1 & s_2
and not
m_1 holding s1_ & s_2 + m_2 holding s1_ & s_2

So there is no tree of module/submodule but only plain hirarchy

/**

• foo1
• @module m_1
• @submodule s_1
  */

/**

• foo2
• @module m_1
• @submodule s_2
  */

/**

• foo3
• @module m_2
• @submodule s_1
  */

/**

• foo4
• @module m_2
• @submodule s_2
  */

There is no documented way to mark an attribute as optional

In theory, one doesn't have to pass any attributes to the constructor, but a majority of widgets and other classes derived from Base require something in order to function.

running entirely from node

Where do you provide name/description/version/url when invoking YUIDocs from node? This constructor function only seems to take the options section?

/**
     * YUIDoc main class

        var options = {
            paths: [ './lib' ],
            outdir: './out'
        };

        var Y = require('yuidoc');
        var json = (new Y.YUIDoc(options)).run();

     * @class YUIDoc
     * @module yuidoc
     * @constructor
     * @param config The config object
     */