Allow nested /// in SassDoc comments.

[jgerigmeyer]

When we want to document how to document something, ideally we could do:

/// /// @colors

But SassDoc strips both sets of ///, leaving just @colors instead of /// @colors. Right now we're using a workaround -- /// // @colors, which results in // @colors -- but that's a bit confusing. Can we submit a PR to SassDoc to make this work?

[jgerigmeyer]

I explored this a bit today. It stems from CDocParser, which automatically strips any occurrence of /// from the comments. I'm not sure what the best solution is... Ideally we could enforce only one comment per line, so that only one occurrence of /// is stripped per line.

Issues filed in CDocParser and SassDoc.

[mirisuzanne]

The related question I got while showing this around was: "can I use a block-comment format, rather than line-comments?" That would likely have to be some marked variant on CSS comment style. Maybe with extra *? I assume that would be a new story, but is it even feasible using SassDoc?

/***
  Some way to have comment blocks
  without marking every line?
  @group api
***/

[jgerigmeyer]

I'm pretty sure SassDoc used to support that, but intentionally dropped it: SassDoc/sassdoc#326 (comment)

[mirisuzanne]

Yeah, that's partly because they only support Sass. We also support CSS for the basic features, making it a more reasonable option for us. But if we'd have to go through them, likely an issue.

[jgerigmeyer]

If we fork SassDoc we could pretty easily enable block comments, and see if it breaks anything else. SassDoc/sassdoc#467

[jgerigmeyer]

I submitted a PR to CDocParser that seems to fix this (FWeinb/CDocParser#17), and opened a new Herman PR using that fork (#220).