Supporting inline comments

[lozandier]

In the future, can Sass authors have a .scss or .sass file be parsed by SassDoc with inline comments (//) instead of comments that can be generated?

[KittyGiraudel]

https://github.com/HugoGiraudel/SassDoc/issues/39

[lozandier]

After reviewing your comments for issue #39, I'll rephrase my question now aware plans for .sass support are not planned yet:

Will the current version of SassDoc have a milestone towards accepting inline comments (//) as an alternate way of annotating stylesheets for SassDoc to then parse or limitations with ScssCommentParser prevents this?

[KittyGiraudel]

Short answer: no.

Long story: some day. Given the fact SCSS is much more widely adopted than Sass, we are not going to spend time working around Sass for now. If someone feels like doing SassCommentParser, we'll see what we can do to plug it in.

[lozandier]

As far as I know, //--being a core Sass feature to be able to have comments in contexts CSS wouldn't allow you to leave comments-- also works within .scss files, as well as as .sass files (at least most recent versions of Sass allows them in .scss, as well as in .sass files).

In cases where you don't want to minify your output yet but don't want to have the output filled with comments with no purpose other than for SassDoc, the ability to use inline comments (//) would seem ideal.

[KittyGiraudel]

I got your point and I totally agree.

Now there are 2 things here:

• Allowing inline comments.
• Allowing .sass files

First, we have built our parser upon CDocParser, which is a C-style comment parser (so /** */ exclusively). If we were to allow inline comments, we would have to massively extend CDocParser.

Secondly, it is not all about comments but also functions and mixins definitions. Both are defined differently in Sass and SCSS. We rely on ScssCommentParser, which only works for SCSS declarations. If we wanted to allow .sass files, we would have to use SassCommentParser (which doesn't exist yet).

[lozandier]

To clarify what I mean, here's an example of what I hope SassDoc would allows us to do with the declarations needed for it to work:

/**
 * Adds `$value` at `$index` in `$list`.
 *
 * @author Hugo Giraudel
 *
 * @ignore Documentation: http://sassylists.com/documentation/#insert-nth
 *
 * @requires is-true
 *
 * @param {List}   $list  - list to update
 * @param {Number} $index - index to add
 * @param {*}      $value - value to add
 *
 * @throws List index $index is not a number for `insert-nth`.
 * @throws List index $index must be a non-zero integer for `insert-nth`.
 *
 * @return {List | Null}
 */

To this:

// Adds `$value` at `$index` in `$list`.

// @author Hugo Giraudel
// @ignore Documentation: http://sassylists.com/documentation/#insert-nth
// @requires is-true

// @param {List}   $list  - list to update
// @param {Number} $index - index to add
// @param {*}      $value - value to add

// @throws List index $index is not a number for `insert-nth`.
// @throws List index $index must be a non-zero integer for `insert-nth`.
// @return {List | Null}

[KittyGiraudel]

I've understood.

[lozandier]

Sorry for the confusion, my browser didn't update to allow me to see the comment you left 20 minutes ago; thanks for the clarification.

On Tue, Jul 8, 2014 at 1:29 PM, Hugo Giraudel notifications@github.com wrote:

I've understood.

— Reply to this email directly or view it on GitHub https://github.com/HugoGiraudel/SassDoc/issues/75#issuecomment-48395570.

Kevin Lozandier lozandier@gmail.com lozandier@gmail.com

[KittyGiraudel]

So, closing.