Dropping C-style comments

[KittyGiraudel]

We initially supported C-style comments because I wrote the very first version of the parser and it was the easiest thing to parse for me since I am a big old blockhead. Then we allowed inline comments because libraries using SassDoc such as SassyLists output C-style comments, polluting the user's CSS. This was especially relevant in online playgrounds such as SassMeister.

I cannot find a good reason to use C-style over inline comments for SassDoc. They are longer and likely to be confusing in regard to usual CSS comments. Also, there are case where C-style comments simply fail:

/**
 * The CSS selector for a special button.
 *
 * @example
 *   #{$special-button-selector} {
 *     font-weight: bold;
 *   }
 * 
 */
$special-button-selector: '.button.special-button';

Undefined variable: "$special-button-selector".

Also it might be worth nothing that both CSS Guidelines and Sass Guidelines recommend using inline comments when documenting Sass code. It makes sense. C-style is for CSS, inline for Sass.

Back to my initial idea: what if we dropped C-style comments altogether? Having a single type of documentation is enough and less confusing for the end user. Also, allowing C-style comments for SassDoc might encourage library authors to pollute users' CSS with massive comment blocks.

@SassDoc/owners What do you think?

PS: this is now or never. API break.

[lolmaus]

The main problem with using block comments for documentation is that it pollutes the resulting CSS. If a library uses block comments, then the CSS of all websites using that library will be bloated with the libraries documentation.

I think you should keep supporting block comments forever, but you should edit all official examples to use line comments and warn library authors against using block comments (both in documentation and in SassDoc console output).

[pascalduez]

So far I can't find any good use case for C-style comments neither.
Especially because SassDoc only support Sass items, that would never appears in the resulting CSS. So they don't need to carry their comments with them.

I'm fine with dropping them, as long as it won't involves huge refactor for v2.0.
Actually it should rather be at the CDocParser level ?

If we keep them, then indeed, we should forewarn in the docs.

[valeriangalliat]

I'm fine with dropping them, as long as it won't involves huge refactor for v2.0.

👍

And I don't think it will affect SassDoc at all, it's just about scss-comment-parser.

If we keep them, then indeed, we should forewarn in the docs.

👍

[pascalduez]

And I don't think it will affect SassDoc at all, it's just about scss-comment-parser.

Whow okay, easy-peasy-lemon-squeezy then ?

[valeriangalliat]

Well my link was wrong, it was just about the code extraction, but not the comments matching/parsing.

A simple way to disable C-style comments was to pass something that will never match as blockCommentStyle to CDocParser.CommentExtractor, so in scss-comment-parser:

var extractor = new CDocParser.CommentExtractor(scssContextParser, {
  blockCommentStyle: 'NOPE',
});

This is working fine for me, but we should be able to pass something like false to disable it at all, we'll see with @FWeinb to add this support in CDocParser.

[KittyGiraudel]

Can someone write the best Regex possible to upgrade from C-Style to inline comments? I know, this is hard.

[valeriangalliat]

Well, we could say:

• s,^/\*\*,///, (replace lines that begin with /** by ///).
• s,^ *\*/,///, (replace lines that begin with potential space plus */ by ///).
• s,^ *\*,///, (replace lines that begin with potential space plus * by ///).

So:

find . -name '*.s[ac]ss' -exec sed -i '' 's,^/\*\*,///,;s,^ *\*/,///,;s,^ *\*,///,' {} + # BSD/Mac `sed`
find . -name '*.s[ac]ss' -exec sed -i 's,^/\*\*,///,;s,^ *\*/,///,;s,^ *\*,///,' {} + # GNU `sed`

But by all means, this is regex, this is not parser.

[KittyGiraudel]

But by all means, this is regex, this is not parser.

Better than nothing.

[valeriangalliat]

BTW the above regexes were not tested please nobody try this without version control.

@hugogiraudel do you have some SCSS using C-style comments so I can try?

[KittyGiraudel]

Not that I am aware of.

[valeriangalliat]

This reflects the need for a migration script…