is this output expected?

[Christopher Hiller]

Input:

/**
 * @name Debaser
 * @public       
 * @param {string} [name] Unique name of this Debaser instance.
 * @constructor
 */
var Debaser = function Debaser(name) {
    // stuff
};

/**
 * @description Install all stubs in queue.
 * @memberof Debaser
 * @param {Object} [opts] Optional settings object
 * @param {boolean} [opts.persist=false] Do not flush the queue upon installation
 */
Debaser.prototype.debase = function debase(opts) {
    // stuff
};

Output:

<a name="new_Debaser"></a>
##new Debaser([name])
**Params**

- \[name\] `string` - Unique name of this Debaser instance.  

<a name="Debaser#debase"></a>
##debaser.debase([opts])
Install all stubs in queue.

**Params**

- \[opts\] `Object` - Optional settings object  
  - \[persist=false\] `boolean` - Do not flush the queue upon installation  

Notice the lowercase debaser.debase([opts]). Would have expected something like Debaser.prototype.debase([opts]). @instance tag has no effect nor does using @class instead. Not sure if this is a dmd or jsdoc thing.

Of note is there is something else called debaser; is case-sensitivity an issue?

[Lloyd Brookes]

sorry for the delay, just having an exceptionally busy week..

it's not a bug..

debaser.<identifier> signifies instance scope.. Debaser.<identifier> signifies static scope - a class method.. it is the same notation used by the node.js docs.. if you take the Buffer docs, for example:

Buffer.isEncoding signifies is a class method.. whereas the lowercase buf.length represents an instance property.. you are seeing debaser.debase because debase is an instance method..

you can set an @alias on the @module to set a custom instance scope name.. for example, this module has an alias of _.

[Lloyd Brookes]

this is the intended behaviour, so closing..

[Christopher Hiller]

This use of @alias--is it custom functionality? I don't see it mentioned in the docs for alias or the docs for module.

I'm assuming @alias will only work in a CommonJS context? I'm not using CommonJS, and I imagine many potential users aren't either...

How could I write a plugin to modify how the @alias tag is used? Would it be easy to add custom tags?

In my mind, a custom superset of jsdoc would be very cool to support, but I may have mentioned already I feel the default behavior should be in-line with jsdoc. Maybe this behavior should be in a nodejs or commonjs plugin or something?

I could roll out a plugin with custom tags for AngularJS projects, if it was easy to implement plugins for custom tags and overwrite the existing ones!

(You can see how, given my use case, NodeJS-docs style output would be mightily confusing. In this example you can see omitting the class prototype or "imaginary" variable name, and simply grouping by static/instance method would work well.)

[Lloyd Brookes]

Hi, yes my use of the @alias tag on @module is the one piece of custom behaviour i have for a native jsdoc tag - i plan to replace it with a custom tag.. something akin to @theTypicalIdentifierNameUsed ForThisModule (or some tag name that would describe what $ is to jQuery and _ is to Underscore).

[Lloyd Brookes]

I'm assuming @alias will only work in a CommonJS context? I'm not using CommonJS, and I imagine many potential users aren't either...

it's for use with any @module tag, which can be in CommonJS or AMD style.. @module supports both: http://usejsdoc.org/howto-commonjs-modules.html

[Lloyd Brookes]

it's easy to make a plugin, see dmd-examples-highlight as an example.. the core purpose of a plug-in is to distribute your overrides/tweaks.. if you really wanted to you could override the base template of dmd (main.hbs) and start from scratch.. the package must export a single function, with this signature and core behaviour:

module.exports = function(boil){
    boil.registerPartials("your/custom/partials/*.hbs");
    boil.registerHelpers("your/custom/helpers/*.js");
    // anything that might be necessary
};

the custom helpers/partials should be contained within the plugin package.. then distribute and install that plug-in into the project which requires it.. you can then use the plugin as documented on the dmd-examples-highlight readme.

when loading, dmd will first register all its internal partials and helpers, then register the partials/helpers specified with --partial, --helper and finally require in the plugins (which must be installed in your local project) specified by --plugin.. registering these additional partials/helpers will either add to or override partials/helpers in the core set.

[Lloyd Brookes]

here is a doclet with a custom tag:

/**
this function has a wonderful custom tag
@createdIn Nigeria
*/
function customTaggedFunction(){}

if you inspect the --json output by jsdoc2md:

$ jsdoc2md custom-tag.js --json

it includes the custom tag data:

  {
    "description": "this function has a wonderful custom tag",
    "tags": [
      {
        "originalTitle": "createdIn",
        "title": "createdin",
        "text": "Nigeria",
        "value": "Nigeria"
      }
    ],
    "name": "customTaggedFunction",
    "longname": "customTaggedFunction",
    "kind": "function",
    "scope": "global",
    "codeName": "customTaggedFunction"
  }
]

i will write some helpers to make using custom tags easy, but until then - do with this data what you will (i.e. create your own helpers/partials to access and display this data.. you could use the existing dmd data access helpers or write your own)

[Christopher Hiller]

Thanks, I didn't understand how to write a plugin aside from just custom templates.