Closed boneskull closed 10 years ago
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 _
.
this is the intended behaviour, so closing..
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.)
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).
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
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.
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)
Thanks, I didn't understand how to write a plugin aside from just custom templates.
Input:
Output:
Notice the lowercase
debaser.debase([opts])
. Would have expected something likeDebaser.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?