Integrity filter

[pascalduez]

Idea: add a new filter that compare the number of documented params and effective code params.
Same for map properties.

Warn in console if not equal.

I've been working with mixins at 10+ params (sigh) recently and it's really easy to forget to update the comments in case you add or remove a param.

[valeriangalliat]

Really good idea. Also could warn for name mismatch... really easy to get the doc out of date with the code, that's the problem with every single dynamically typed language.

[KittyGiraudel]

I'm wondering whether this issue would be made irrelevant with SassDoc/sassdoc#304.

[valeriangalliat]

@hugogiraudel For a map yep, but not for function/mixins arguments I guess.

[KittyGiraudel]

SassDoc/sassdoc#304 should be thought as a way for SassDoc to be more aware about the code. Function and mixin arguments should be quite easy to parse.

[pascalduez]

I had that issue in mind, but I feel like what's described in there is addressing only part of the problem (default values).

Here is just a fairly dumb workaround that can be used right away.

If we go the "parser way", it would be interesting to be able to create and fill a full annotation from code.
But that might be a bit tricky, like determining properties or parameters types, and first resolve the alias if any...

There will be quite some decisions to take.
How to had a description to it then ?
If a parameter is documented, but the parser found values are not matching, should it overwrite them?
[ ... ]

[KittyGiraudel]

But that might be a bit tricky, like determining properties or parameters types, and first resolve the alias if any...

Only the type might be tricky in case the parameter has no default value. Else, you can guess.

How to had a description to it then ?

You don’t. Either you let the parser quick grab parameters, or you document them yourselves.

If a parameter is documented, but the parser found values are not matching, should it overwrite them?

If a parameter is documented, the parser does not do anything.

[pascalduez]

If a parameter is documented, the parser does not do anything.

Then we loose the main idea behind the two issues: keeping comments and code in sync :)