SassDoc
Add ability to infer default values when compiling
If I have some map, or mixin, with a documented property, it might be nice to try to parse the SCSS following the comment to try and infer its default value. Such that writing this SCSS:
// Main colour palette.
// @prop {Color} main-background - Deep, blueish gray
// @see {function} colour
// @type Map
$colours: (
"main-background": rgb(61, 75, 92)
);
Should be parsed exactly the same as if we were to explicitly write the default value:
// Main colour palette.
// @prop {Color} main-background (rgb(61, 75, 92)) - Deep, blueish gray
// @see {function} colour
// @type Map
$colours: (
"main-background": rgb(61, 75, 92)
);
The benefits of doing this - well, having documentation that is up to date is pretty important. I can see a few cases where an author will update their SCSS files, and forget to change a variable in the doclet. Would be a nice feature to have!
I like this idea. We can do this by adding a resolve function to src/annotation/annotations/property.js, parsing item.context.value for each item in given data:
// ...
resolve(data) {
data.filter(i => 'property' in i).forEach(item => {
let props = someMagicWith(item.context.value);
item.property = item.property.map(prop => {
if (!('default' in prop)) {
prop.default = props[prop.name];
}
return prop;
});
});
},
// ...
Though SassDoc's purpose is not to be a proper SCSS parser (it's already having difficulties parsing annotations as you could point out in #303 :smile:), so if we end up implementing this, it will probably be a fairly dumb parser, that will fail in complex cases.
Indeed. You might like to have a look at gonzales-pe for this, instead of rolling your own. :smiley:
The last time I check Gonzales-pe it could not handle most of scss, so that isn't an option.
We already tried gonzales-pe. It does not suit our needs. Also I'd like to avoid making SassDoc a full Sass parser.
