Question : How to add custom code to check to jscs-jsdoc module?

[buenjybar]

Hi,

i have a specific rule that allow us to use multiple "@returns" tags in our documentation. i have modified the check-return-type.js file in order to take this in consideration. My question is how could i integrate it in my project?

is there a plugin structure like jsdoc3.4 to override a part of the code ? or should i copy the entire jscs-jsdoc in my project ?

with regards,

[qfox]

Heya. Thanks for a question.

I don't know much about jsdoc3.4 plugin structures to answer it correctly, but if I got it right the answer is no, jscs-jsdoc doesn't have their own plugin method, but you can base your own rules with jscs-jsdoc's. So I guess you can copy-paste just the check-return-type rule, rename it, fix it, and use it.

p.s. To have 2 @returns statements is quitely strange case, isn't it? What's the case unless it's secret?

[buenjybar]

HI @zxqfox,

first i would like to thank you for the quick reply. i made my modification in check-return-type and it is working fine but i had to fork/copy the entire project in my repository.

what i was thinking is i could load the 'scs-jsdoc plugin first then i will create my own jscs plugin that will override your check-return-type behavior but i don't think this is possible ( the error will be already raise)

basically the jsdoc plugin structure allow your to register function during the jsdoc process. so you can customize the behavior of jsdoc to match your needs.

jsdoc @return is kind of messy when you need to expose a nested object structure here is an example of how i will use it.

/**
* get properties 
* @return {object} value
* @return {number} value.id
* @return {string} value.description
*/

with regards,

[qfox]

I guess we can allow this behaviour with an option since it looks valid and non-conflictable. Do you mind about PR? ;-)

The problem with jscs-jsdoc is there are no namespaces for rules and it's just the one rule for jscs, but several rules for jscs-jsdoc. It's kind of poor subplugin system.

To override you could have to incapsulate jscs-jsdoc (instead of forking), redefine just needed parts like validate-jsdoc.js and check-return-types.js, and export the new ones with the same API. It's not as beauty as it could be, but possible.

[buenjybar]

well my commits is a pseudo fix, i don't think this is the best approach but it doing the trick.

here is the code:

module.exports = checkReturnTypes;
module.exports.tags = ['return', 'returns'];
module.exports.scopes = ['function'];
module.exports.options = {
    checkReturnTypes: {allowedValues: [true]}
};

/**
 * Checking returns types
 *
 * @param {(FunctionDeclaration|FunctionExpression)} node
 * @param {DocTag} tag
 * @param {Function} err
 */
function checkReturnTypes(node, tag, err) {
    // try to check returns types
    if (!tag.type || !tag.type.valid) {
        return;
    }

    var returnsArgumentStatements = this._getReturnStatementsForNode(node);
    returnsArgumentStatements.forEach(function(argument) {
        if (tag.value && tag.value.indexOf('.') > -1) { // <<<<< add support for nested @returns description
            return;
        }

        if (!tag.type.match(argument)) {
            err('Wrong returns value' , argument.loc.start);
        }
    });
}

with regards,