// FIXME: helma.plugin relies heavily to variable JSDOC.Symbol.srcFile for helma properties file detection
// FIXME: a ' wrapped in a # comment, i.e. " # doesn't " silently breaks the parsing resulting in properties being omitted
JSDOC.PluginManager.registerPlugin(
/**
* In helma objects are defined by files with the extension .properties.
* So for jsdoc to work we need to parse these properties files and treat
* them like object constructors.
* In helma properties files comments are marked by a leading # .
* That differs from JS, so the rule is to make JS doclet comments
* after the # . For example:
* # /**
* # * @class
* # * @name Mate
* # * @type Human
* # * @augments Person
* # */
//*/
"JSDOC.Helma",
{
/**
* jsdoc-toolkit detects the doclet start end end correctly but the
* contents inside still need to be cleaned of the # .
*/
onDocCommentSrc : function(docComment) {
// check if properties are parsed
if (/\.properties$/i.test(JSDOC.Symbol.srcFile) === true) {
// remove #
docComment.src = docComment.src.replace(/#/gi, "");
// apply some standard formating that happens inside the DocComment.unwrapComment
// but fails because the # are removed by a call to this plugin later.
docComment.src = docComment.src.replace(/(^\/\*\*|\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
}
return;
},
/**
* In helma properties files the object properties are declared just by name,
* without reference to the object they belong to. Because of that jsdoc-toolkit
* gets the name and alias wrong. So take the value of the @member tag and
* insert it into the name and alias.
* Within helma it is possible to declare prototype functions without atatching
* them to the prototype: "MyPrototype.prototype.myFunction = function()" can be written
* as "function myFunction()" . Of course that breaks the JsDoc parsing since it puts the
* function into global namespace. Setting helmacomp=true on the commandline or in a conf
* file executes the memberOf resolving for every symbol preventing that error.
*/
onSetTags: function(symbol) {
// check if symbols origin is in a properties file or helmacomp was set
if ((/\.properties$/i.test(symbol.srcFile) === true) || (JSDOC.opt.D.helmacomp != undefined)) {
// _children are documented as private because of the _. Uncomment the
// following code block to prevent that.
/*
if (/_children/i.test(symbol.name) === true) {
symbol.name = "children";
symbol.alias = symbol.name;
}
*/
if (symbol.memberOf != "") {
symbol.name = symbol.memberOf + "." + symbol.name
symbol.alias = symbol.name;
}
}
return;
}
}
);