Write a real parser

[KittyGiraudel]

Regular expressions are not powerful enough.

We need to write a real parser.

[KittyGiraudel]

First draft: https://gist.github.com/HugoGiraudel/5614be5d1f02eb25c175.

[pascalduez]

Just an quick idea, not sure it will be the best fit, but building on top of existing CSS parsers like rework or PostCSS ?

[KittyGiraudel]

Well, I am not sure. As far as know, both are CSS parsers. What we need here is a documentation parser.

[alademann]

Agreed @HugoGiraudel

[KittyGiraudel]

Thanks for the input Aaron, I'll keep working on this to see if it can go anywhere.

[KittyGiraudel]

Latest version: https://gist.github.com/HugoGiraudel/5614be5d1f02eb25c175. Getting closer.

Edit: I added a isValidType function but it's not used yet.

[alademann]

Latest version from Hugo... https://gist.github.com/HugoGiraudel/9f44eb6b3d3391abb384

[KittyGiraudel]

Progress:

• successfully parsing a function with any option
• successfully parsing a mixin with any option
• successfully parsing a variable with any option (not that there are many)

To do:

• make sure we don't treat regular comments as documentation (currently fails)
• try any weird case with multiples spaces before or after certain tokens (some of them already covered)
• try to plug it into SassDoc core (should be easy)
• improve code quality (it's a mess imo)

[KittyGiraudel]

Managed to get some things done:

• plug parser into code base (branch real-parser)
• successfully documentize the examples folder as it was with the regex version (~50 items across almost 30 files)

I found an issue in the process: a function with a single line comment isn't documented, for instance a single @alias line.

// @alias other-function

@function whatever($whatever) {
  @return whatever;
}

Meanwhile, this works:

// @requires other-function
// @alias other-function

@function whatever($whatever) {
  @return whatever;
}

[KittyGiraudel]

Fabrice's work: https://github.com/FWeinb/CDocParser. Looks very promising.

[KittyGiraudel]

New branch now using CDocParser and ScssCommentParser. Will deploy 1.0.0 shortly.