Add ability to use inline comments

[pascalduez]

I remember we talked about it, but did not had the case yet.
See SassySVG test files

[KittyGiraudel]

You are not supposed to compile your files in any format but "compressed" where CSS comments don't show up.

[pascalduez]

For production styles, this is no issue, since they should be compressed/minified.

But for all the development phases, this is really annoying IMO.
Imagine a large project with many libs and partials.
I really like to be be able to inspect the output CSS, and not only in a devtools, but have the whole file in front of me. This is the best way to spot errors, pitfalls (extend), and areas of optimization.
There are cases where devtools are not of much use, and direct CSS inspection is required.
I also like to put small C style comments as markers while developing.

This is more of an opinions thing here, and thinking of possible solutions/workarounds.

[KittyGiraudel]

Apart from allowing inline comments, there is not much we can do.

[pascalduez]

Apart from allowing inline comments, there is not much we can do.

Trying to find the issue where @FWeinb explained inline comments where hard to parse. Because no way to distinguish documentation comments from regular ones.

Maybe inline comment with markers to delimit the doc block:

// **
// A nice function
//
// @param {Map} $map (()) - Param desc
// 
// @returns {String} returns desc
// *

///
// A nice function
//
// @param {Map} $map (()) - Param desc
// 
// @returns {String} returns desc
///

///
/// A nice function
///
/// @param {Map} $map (()) - Param desc
/// 
/// @returns {String} returns desc
///

Gosh, for some reasons they looks kinda weird. The second one might be acceptable. Searching.
http://sassmeister.com/gist/dae6f6c67a46c854408b

[gisu]

Personally i found this also a little bit annoying, thats why i have only a modified version of sassylists in Kittn included - too many comments.
Is there really no other way to tell the parser which blocks it should use? Like

//**
//  Comment
//  @param .....
//*!

[KittyGiraudel]

As much as possible I would like to avoid introducing a new standard.

I'm curious about @valeriangalliat and @FWeinb's opinions on this.

[valeriangalliat]

A common pattern is to use /// for documentation in C++ style comments.

Well @pascalduez proposed this just above.

[pascalduez]

As much as possible I would like to avoid introducing a new standard.

Agreed. If possible...
This is also why we should avoid using stars for delimitation e.g.: //**, too confusing.

A common pattern is to use /// for documentation in C++ style comments.

Oh, interesting.
http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

[KittyGiraudel]

There are reasons why we don't/can't parse inline comments, could they be // or ///.

[gisu]

Than /// so the dev can write native sass comments that the parser not see.

[KittyGiraudel]

I want @FWeinb's answer. He's the one who wrote the parser; he's the one able to tell whether or not we can use a syntax that is not delimited by an opening and a closing sequences.

If it's possible, then I'm in favor of ///. Else, we'll think of something else.

[valeriangalliat]

Well I thought the idea for the parser was to find a way to differenciate "normal" comments from documentation comments.

The difference for C style comments is the additional * on the opening sequence. The difference for C++ style comments can be to add a third / like proposed.

[FWeinb]

Sure we would be able to write such a parser. But I think that it would be better to have 1 (one) standard for comments that are taken into account. Things like /// and // ** would introduce complexity that I would like to not have to think about.

SassDoc is an opinionated documentation framework, If you would like to use it you have to create special crafted Scss code comments.

If someone feels like it we can write some transformers that care about rewriting comments but I don't like to have the complexity in SassDoc.

@pascalduez Why don't you use source maps for linking css to the scss code.

[pascalduez]

I really understand your concerns, and I was pretty happy with the way SassDoc deal with this until then.
But when I see the resulting CSS, I'm starting to think there's something not ideal happening.

Imagine a project which depends on a couple of libs like SassyList, with dozens of functions, and the same project SassDocs its code as well, the amount of comments in the CSS files might be a problem, and is not giving a quality feeling actually.

Source maps are not really an option, as I tried to explain, there are often cases where directly checking the output CSS files is required, and also desired.
Quality check, optimizations, some twisted debugging.
Such amount of comments might hinder that process.

I'm neither happy with hackish things like //**, but knowing that /// is some kind of standards in other languages, makes me a bit more confident.

There was already a couple of issues regarding allowing inline comments.
Let's keep this one open, and see if there's more "complaints" ?