search

SassDoc / sassdoc

Release the docs!
http://sassdoc.com
MIT License
1.41k stars 56 forks source link

Allow documenting SassDoc comments. #519

Open jgerigmeyer opened 6 years ago

jgerigmeyer commented 6 years ago

This is related to #428 -- and really stems from CDocParser, used by scss-comment-parser, (see issued filed there: https://github.com/FWeinb/CDocParser/issues/16) -- but relates to a SassDoc use-case, so I wanted to document it here as well.

Within a SassDoc comment, I would like to document how to make a SassDoc comment. For example:

/// Here is how to add a comment:
/// /// I am a comment.

Right now, CDocParser strips to to just:

Here is how to add a comment:
I am a comment.

Instead of the desired:

Here is how to add a comment:
/// I am a comment.

Is there a good way to do this? Could there be an option to mark a section of text as "escaped", so it won't be parsed as a comment? Or enforce only one comment per line?

jgerigmeyer commented 6 years ago

I think I've found a way to address this in CDocParser without breaking other use-cases: https://github.com/FWeinb/CDocParser/pull/17

steffenpedersen commented 5 years ago

Hi @jgerigmeyer, is this still an issue? I can see, that you made some changes in CDocParser 😃

jgerigmeyer commented 5 years ago

@steffenpedersen Well, sort of and also not really. :)

It's been fixed in CDocParser v0.15.0, but SassDoc (through scss-comment-parser) is still using the older v0.13.0, where this is not fixed. I don't fully understand why (I've been using SassDoc with CDocParser v0.15.0 for nearly a year without issue), but see @pascalduez's comment: https://github.com/FWeinb/CDocParser/issues/16#issuecomment-356220495

pascalduez commented 5 years ago

Because 0.14 enables a new feature that we would prefer to get documented and unit tested. Otherwise it might get lost in limbo :) Will try to find some time to get this done.