Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
buenjybar opened this issue Apr 11, 2016 · 4 comments
Open

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

buenjybar opened this issue Apr 11, 2016 · 4 comments
Labels

Comments

@buenjybar
Copy link

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
Copy link
Member

qfox commented Apr 11, 2016

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?

@qfox qfox added the question label Apr 11, 2016
@buenjybar
Copy link
Author

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
Copy link
Member

qfox commented Apr 12, 2016

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
Copy link
Author

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,

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants