Add ability to infer default values when compiling

[ben-eb]

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!

[valeriangalliat]

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 😄), so if we end up implementing this, it will probably be a fairly dumb parser, that will fail in complex cases.

[ben-eb]

Indeed. You might like to have a look at gonzales-pe for this, instead of rolling your own. 😃

[FWeinb]

The last time I check Gonzales-pe it could not handle most of scss, so that isn't an option.

[KittyGiraudel]

We already tried gonzales-pe. It does not suit our needs. Also I'd like to avoid making SassDoc a full Sass parser.

[ben-eb]

Alright, fair enough. 😄