stouf/jsdox — pull request #1 by boneskull (2013-09-02 20:10:26+00:00)
Title: support for @see and @constructor

Hi, I'm not sure sutoiku/jsdox is being maintained since you left a PR some months ago and it never got merged in, but I thought you may be interested in this.

jsdox now supports the `@constructor` tag. Use it in combination with `@class` like so:

```javascript
/**
* Filter pseudoclass
* @class Filter
* @constructor
* @param {Object} obj Object representing Filter
*/
var Filter = function Filter(obj) {
extend(this, obj);
};
/**
* Sets the current filter to be this Filter
* @method setCurrent
* @returns {Function|promise|Q.promise}
*/
Filter.prototype.setCurrent = function () {
return fogbugz.setCurrentFilter(this);
};
```

The generated documentation will look like:

> class fogbugz.Filter
> --------------------
> Filter pseudoclass
>
> **Parameters**
>
> **obj**: *Object*, Object representing Filter
>
> **Methods**
>
> fogbugz.Filter.setCurrent()
> ---------------------------
> Sets the current filter to be this Filter

Furthermore the `@see` tag is now supported. This may or may not work anywhere else but GitHub because it relies on certain HTML `id` attributes being set. But for GitHub anyway, it will automatically create a named anchor for every header. And jsdox creates headers, so we can link to them. Using `@see fogbugz.logon` below will link to the `logon` method of the `fogbugz` module:

```javascript
/**
* @module fogbugz
*/
var fogbugz = {
/**
* Manually sets a login token if you have one by some other means.
* @see fogbugz.logon
* @method setToken
* @param {string} token FogBugz API logon token
*/
setToken: function setToken(token) {
// stuff emitted for brevity
},

/**
* Logs you into FogBugz based on contents of `fogbugz.conf.json`.
* @method logon
* @returns {Function|promise|Q.promise} Promise
*/
logon: function logon() {
// stuff omitted for brevity
}
};
```

If you want to link to a module, jsdox will create a heading called "module foo"; GitHub sanitizes the string value of the header to create the anchor name, so to do that you will write `@see module foo`; likewise if you are linking to a class `@see class Foo`; or a class in a module: `@see class someModule.Foo`.

I have no tests for this written, but I may write them in the near future. If I do that I'll PR back to sutoiku/jsdox for whatever good that'll do; if it doesn't get accepted I'll contact @sutoiku and perhaps volunteer to take over maintenance of the module.