Can parse CSS rule code contexts, too.

[carljm]

Hi! We'd like to use SassDoc as part of a "living styleguide" system for our projects, and for this to work it needs to have the capability to annotate CSS rule blocks as well as functions/variables/mixins/placeholders. This pull request adds that capability to the comments context parser.

I see that the broad concept has been rejected before, on "do just one thing" grounds (e.g. see SassDoc/sassdoc#268), but I'd like to request re-consideration. Accepting this small PR does not mean changing the primary supported purpose of SassDoc in any way, it just adds a bit more flexibility for those of us who want to experiment with extending SassDoc in "off the beaten path" ways, without harming or impacting the existing uses at all.

Thoughts? Thanks for considering.

[KittyGiraudel]

For some reason, I didn’t get notified for this PR so I’ll ping other core contributors as well: @valeriangalliat @FWeinb @pascalduez. I will reply to this tomorrow as soon as I get to work. :)

[valeriangalliat]

Missing leading {

[valeriangalliat]

Also maybe makes more sense to call it code instead of value.

[carljm]

Yeah, I debated about the names. I chose name and value for consistency with all the other types, but if that consistency doesn't matter it would probably be better to use selector and body.

And the leading { and trailing } of the body are both removed, but if you think it's better to include them I can certainly do that.

[carljm]

(It looks like the trailing } is there, but it's not -- that's actually part of a nested rule.)

[valeriangalliat]

Ahh, indeed, just the fact that the code was ending with a } and not beginning with one was bugging me.

And the {} are removed for other annotations so you're right that's the right way to do. 👍

The mixin uses name and code so it's still consistent to use code for CSS rules too, though selector and body also really make sense... let's see @SassDoc/owners's opinion.

[pascalduez]

Conceptually I'm in favor of this, I feel like it's time to let people be able to hack around SassDoc, so they can build custom themes that fits their needs, new directions, etc...
At the time of PostCSS, CSS modules, and all possible new concepts to come, it might be wise not to lock SassDoc evolution capabilities.
Which doesn't mean SassDoc core (default theme) have to change guidance, if we still want to focus on Sass libraries, we can.

I'll have a look at the code later on.

[KittyGiraudel]

Ohai.

Thanks again for bringing this on the table @carljm (and @ericam).

On the code side, it looks simple and clever enough to be merged without worrying too much, so I’d go with a yes. It looks like a nice addition that does not introduce any backward incompatibility, therefore I do not see any reason to prevent this or decline this pull request.

Now, on the documentation side I am wondering whether / how we should document this. I would be in favor of not promoting this too much if we want SassDoc to remain an API documentation tool. That being said, we could make this reply from the FAQ a bit more elaborate, perhaps including a link to this pull-request and any further work performed by the OddBird team.

On top of that, it would be interesting to document this somewhere else in the “Custom theme” section, so people know that they can use this feature if they build their own theme. Indeed, I must say I don’t really want to adapt the default theme to support CSS rules, although maybe we should. Thoughts?

[carljm]

Thanks for the review and discussion! I don't personally have any opinion on how or whether the SassDoc documentation, FAQ, or default theme should be updated, but if you all decide that they should be, I'm happy to submit a PR to SassDoc for that as well. Just let me know.

Regarding this PR, let me know if you want the keys updated from name and value to either name and code or selector and body. That's the only outstanding question I'm aware of.

[carljm]

What's the next step here? Sounds like the consensus so far is in favor of merging -- any changes needed first? Anyone else need to weigh in?

[KittyGiraudel]

I would have loved to have @FWeinb but I don’t think it’s gonna happen. @pascalduez, @valeriangalliat, all good?

[valeriangalliat]

Looks good to me

[pascalduez]

👍

[pascalduez]

Let's see this as a shy hello sign to future evolutions and theme hackers.
But feels like we would need a serious planning at some point if we want to do things right.
Especially the data interface naming.

[pascalduez]

Thanks for the PR @carljm !

Available as of scss-comment-parser@0.8.0 and sassdoc@2.1.16

[carljm]

Thanks @pascalduez !