Add ability to use inline comments #143

Closed
pascalduez opened this Issue Jul 29, 2014 · 59 comments

Comments

Projects
None yet
9 participants
@pascalduez
Member

pascalduez commented Jul 29, 2014

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

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 30, 2014

Member

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

Member

HugoGiraudel commented Jul 30, 2014

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

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

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.

Member

pascalduez commented Jul 30, 2014

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.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 30, 2014

Member

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

Member

HugoGiraudel commented Jul 30, 2014

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

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

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

Member

pascalduez commented Jul 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@gisu

gisu Jul 30, 2014

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 .....
//*!

gisu commented Jul 30, 2014

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 .....
//*!
@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 30, 2014

Member

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

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

Member

HugoGiraudel commented Jul 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 30, 2014

Member

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

Well @pascalduez proposed this just above.

Member

valeriangalliat commented Jul 30, 2014

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

Well @pascalduez proposed this just above.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

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

Member

pascalduez commented Jul 30, 2014

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

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 30, 2014

Member

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

Member

HugoGiraudel commented Jul 30, 2014

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

@gisu

This comment has been minimized.

Show comment
Hide comment
@gisu

gisu Jul 30, 2014

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

gisu commented Jul 30, 2014

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

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Jul 30, 2014

Member

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.

Member

HugoGiraudel commented Jul 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 30, 2014

Member

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.

Member

valeriangalliat commented Jul 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 30, 2014

Member

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.

Member

FWeinb commented Jul 30, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

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" ?

Member

pascalduez commented Jul 30, 2014

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" ?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 30, 2014

Member

If we talk "standards" here than I think that the JavaDoc way is the most used standard out there. I am just concerns that we just want to support something wit no real benefit. If you want to use SassDoc you have to use the right annotations anyway so you can just write the documentation as the documentation framework is expecting.

Am 30.07.2014 um 17:30 schrieb Pascal Duez notifications@github.com:

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 "complains" ?


Reply to this email directly or view it on GitHub.

Member

FWeinb commented Jul 30, 2014

If we talk "standards" here than I think that the JavaDoc way is the most used standard out there. I am just concerns that we just want to support something wit no real benefit. If you want to use SassDoc you have to use the right annotations anyway so you can just write the documentation as the documentation framework is expecting.

Am 30.07.2014 um 17:30 schrieb Pascal Duez notifications@github.com:

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 "complains" ?


Reply to this email directly or view it on GitHub.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

But we should not overlook that Sass is about producing CSS at the end of the stack, and ideally SassDoc should be transparent.

Member

pascalduez commented Jul 30, 2014

But we should not overlook that Sass is about producing CSS at the end of the stack, and ideally SassDoc should be transparent.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Jul 30, 2014

Member

SassDoc can't work with CSS. It is only possible to annotate Sass features (like mixins, functions or variables). I don't quite understand your problem here. I think of SassDoc as an opinionated way to auto generate Sass Documentation (scss documentation to be 100% correct). So we have nothing to do with CSS.

Member

FWeinb commented Jul 30, 2014

SassDoc can't work with CSS. It is only possible to annotate Sass features (like mixins, functions or variables). I don't quite understand your problem here. I think of SassDoc as an opinionated way to auto generate Sass Documentation (scss documentation to be 100% correct). So we have nothing to do with CSS.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 30, 2014

Member

Let me try to phrase this differently.
Sass goal is to output CSS.
SassDoc to document SCSS files. It's just an additional tool.
"SassDoc should ideally be transparent", means there should be no traces of it in the final output (CSS). Especially if that might make the developer work harder at the end.

Like cooking stewed apples without removing the seeds, core and skin... ;-)

Member

pascalduez commented Jul 30, 2014

Let me try to phrase this differently.
Sass goal is to output CSS.
SassDoc to document SCSS files. It's just an additional tool.
"SassDoc should ideally be transparent", means there should be no traces of it in the final output (CSS). Especially if that might make the developer work harder at the end.

Like cooking stewed apples without removing the seeds, core and skin... ;-)

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
Member

valeriangalliat commented Jul 30, 2014

Stephen Colbert popcorn meme

@pascalduez

This comment has been minimized.

Show comment
Hide comment
Member

pascalduez commented Jul 31, 2014

fernandel_e_toto

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 31, 2014

Member

Here's how I see it:

  • I'm raising this issue because I feel it is important an impacting SassDoc users.
  • It would be interesting to see whether there are more similar feedback coming.
  • We are discussing it in a friendly and constructive way (hopefully).
  • You guys are the "core maintainers", so the final decision is up to you, and if you feel it's not worth the effort, then it's totally fine and legit.

Personally, I think this could be a brake in my usage of SassDoc.

Also just stumbled upon the fact that Docco support scss and inline comments.

Edit: some more examples
https://github.com/chriseppstein/sassdoc#sassdoc-syntax
https://github.com/mattbieber/sassdocjs#roadmap

Actually the best scenario would be to have the choice on which comment type to use.

Member

pascalduez commented Jul 31, 2014

Here's how I see it:

  • I'm raising this issue because I feel it is important an impacting SassDoc users.
  • It would be interesting to see whether there are more similar feedback coming.
  • We are discussing it in a friendly and constructive way (hopefully).
  • You guys are the "core maintainers", so the final decision is up to you, and if you feel it's not worth the effort, then it's totally fine and legit.

Personally, I think this could be a brake in my usage of SassDoc.

Also just stumbled upon the fact that Docco support scss and inline comments.

Edit: some more examples
https://github.com/chriseppstein/sassdoc#sassdoc-syntax
https://github.com/mattbieber/sassdocjs#roadmap

Actually the best scenario would be to have the choice on which comment type to use.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 31, 2014

Member

Well IMO, if people need this, someone will make a fork, or they'll use alternative documentation softwares. Natural selection/evolution, in some way?

Member

valeriangalliat commented Jul 31, 2014

Well IMO, if people need this, someone will make a fork, or they'll use alternative documentation softwares. Natural selection/evolution, in some way?

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Jul 31, 2014

Member

Natural selection/evolution, in some way?

Since I'm almost the only one ranting here, I could take it personally ?
Although I get your idea, that's something inherent with open source somehow.

The fact is, we are not speaking about flavors or tastes here, finding this syntax nicer than the other one. But more about some sort of defect behavior (IMO).

Writing fancy and "opinionated" APIs is one thing, listening to the end users is another.

Member

pascalduez commented Jul 31, 2014

Natural selection/evolution, in some way?

Since I'm almost the only one ranting here, I could take it personally ?
Although I get your idea, that's something inherent with open source somehow.

The fact is, we are not speaking about flavors or tastes here, finding this syntax nicer than the other one. But more about some sort of defect behavior (IMO).

Writing fancy and "opinionated" APIs is one thing, listening to the end users is another.

@simonbuerger

This comment has been minimized.

Show comment
Hide comment
@simonbuerger

simonbuerger Jul 31, 2014

I've been following this project from when Hugo blogged about it - and I recently started trying it out on some of our internal library scss code. After adding annotations to 20+ functions, mixins and variables I find myself agreeing with @pascalduez , the un-minified output (which I do check in development to confirm output is as expected) does look a bit.... meh. 100+ lines of just comments at the top of every CSS file seems worth avoiding.

That said it's not a deal-breaker for me, alternative comment formats would be a nice option though. There are a number of styleguide generators that accept both /** and // that I'm aware of, so there is precedent in this area.

I've been following this project from when Hugo blogged about it - and I recently started trying it out on some of our internal library scss code. After adding annotations to 20+ functions, mixins and variables I find myself agreeing with @pascalduez , the un-minified output (which I do check in development to confirm output is as expected) does look a bit.... meh. 100+ lines of just comments at the top of every CSS file seems worth avoiding.

That said it's not a deal-breaker for me, alternative comment formats would be a nice option though. There are a number of styleguide generators that accept both /** and // that I'm aware of, so there is precedent in this area.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Jul 31, 2014

Member

Since I'm almost the only one ranting here, I could take it personally ?

Not at all, I'm sure you're not the only one to want such a feature, and if it turns out to be a need for some people, the open source "nature" will do its job.

I'm not using Sass and even CSS (so few I don't mention it anymore), so I'm not in favor nor against this behavior. I undrestand it's more than a style question, but I'm nobody to say if it's really a problem if SassDoc's comments are actually "leaked" in the CSS output.

I'm against listning blindly to the end user, but I can't judge this request. I'm just saying if you're not the only one annoyed by this fact, other people will +1 your idea and this would probably mean it's relevant to adapt the API (and while I'm writing this, that's exactly what @simonbuerger did). :p

Member

valeriangalliat commented Jul 31, 2014

Since I'm almost the only one ranting here, I could take it personally ?

Not at all, I'm sure you're not the only one to want such a feature, and if it turns out to be a need for some people, the open source "nature" will do its job.

I'm not using Sass and even CSS (so few I don't mention it anymore), so I'm not in favor nor against this behavior. I undrestand it's more than a style question, but I'm nobody to say if it's really a problem if SassDoc's comments are actually "leaked" in the CSS output.

I'm against listning blindly to the end user, but I can't judge this request. I'm just saying if you're not the only one annoyed by this fact, other people will +1 your idea and this would probably mean it's relevant to adapt the API (and while I'm writing this, that's exactly what @simonbuerger did). :p

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 1, 2014

Member

Keep it cool, keep it constructive, folks.

I am not a huge fan of C-style comments for Sass myself. Essentially because they get printed in the CSS in tools like CodePen or SassMeister where seeing the generated code is not a luxury. Ideally, I would like a syntax that is based on inline comments (//) so that SassDoc comments do not get output no matter Sass' output style, yet without reinventing another way of documenting code (I like /// by the way).

Meanwhile, SassDoc will not supported several syntaxes at the same time. Fabrice doesn't want that, and I could not agree more. This would bring too much complexity to the tool, with no real benefit. If a syntax is not good enough so that we have to move to another one, fair enough. But we won't keep both.

For this very reason, we can't change the syntax without breaking the API. So this won't be before 2.0 anyway. Meanwhile, I will discuss it with Fabrice to see what we can come up with and if we should consider switching to an inline based syntax.

As a last note, I have spoken with @kaelig from The Guardian who is considering documenting his Sass code with SassDoc. He, as well, noticed the CSS comments in the output and then realized it doesn't matter because they don't get printed when compiling as compressed.

Along the same lines, I can't remember the last time I had to closely look at my CSS output to debug anything. DevTools is more than enough in most cases, and if you just want to make sure things are being compiled as expected, it shouldn't be some comments at the top of the file stopping you.

Member

HugoGiraudel commented Aug 1, 2014

Keep it cool, keep it constructive, folks.

I am not a huge fan of C-style comments for Sass myself. Essentially because they get printed in the CSS in tools like CodePen or SassMeister where seeing the generated code is not a luxury. Ideally, I would like a syntax that is based on inline comments (//) so that SassDoc comments do not get output no matter Sass' output style, yet without reinventing another way of documenting code (I like /// by the way).

Meanwhile, SassDoc will not supported several syntaxes at the same time. Fabrice doesn't want that, and I could not agree more. This would bring too much complexity to the tool, with no real benefit. If a syntax is not good enough so that we have to move to another one, fair enough. But we won't keep both.

For this very reason, we can't change the syntax without breaking the API. So this won't be before 2.0 anyway. Meanwhile, I will discuss it with Fabrice to see what we can come up with and if we should consider switching to an inline based syntax.

As a last note, I have spoken with @kaelig from The Guardian who is considering documenting his Sass code with SassDoc. He, as well, noticed the CSS comments in the output and then realized it doesn't matter because they don't get printed when compiling as compressed.

Along the same lines, I can't remember the last time I had to closely look at my CSS output to debug anything. DevTools is more than enough in most cases, and if you just want to make sure things are being compiled as expected, it shouldn't be some comments at the top of the file stopping you.

@simonbuerger

This comment has been minimized.

Show comment
Hide comment
@simonbuerger

simonbuerger Aug 1, 2014

and if you just want to make sure things are being compiled as expected, it shouldn't be some comments at the top of the file stopping you.

Agreed, like I said it's not a deal-breaker by any means for me

and if you just want to make sure things are being compiled as expected, it shouldn't be some comments at the top of the file stopping you.

Agreed, like I said it's not a deal-breaker by any means for me

@kaelig

This comment has been minimized.

Show comment
Hide comment
@kaelig

kaelig Aug 1, 2014

As a last note, I have spoken with @kaelig from The Guardian who is considering documenting his Sass code with SassDoc. He, as well, noticed the CSS comments in the output and then realized it doesn't matter because they don't get printed when compiling as compressed.

I was not super happy about the extra comments in the output but that's not like I'm looking at the CSS all the time so I can live with it.

kaelig commented Aug 1, 2014

As a last note, I have spoken with @kaelig from The Guardian who is considering documenting his Sass code with SassDoc. He, as well, noticed the CSS comments in the output and then realized it doesn't matter because they don't get printed when compiling as compressed.

I was not super happy about the extra comments in the output but that's not like I'm looking at the CSS all the time so I can live with it.

@gisu

This comment has been minimized.

Show comment
Hide comment
@gisu

gisu Aug 1, 2014

The Problem is that Sass will render all Comments at the Beginning from the CSS Files (because the most functions will come first). With 100 or 200 lines off comment code is not a big issue, but when you get over 1000 Lines Comment code, is a little bit annoying. Thats why i didn't include Sass Libraries with Bower, otherwise i will get too much comment code.

Good i not the biggest Issue, you can Scroll down thats it - when no Sass Error come you will hold the Position in Sublime. With a compile error you need to scroll again. On the other side is a good tool for commenting code (would be perfect when it will document BEM and normal Elements g).

gisu commented Aug 1, 2014

The Problem is that Sass will render all Comments at the Beginning from the CSS Files (because the most functions will come first). With 100 or 200 lines off comment code is not a big issue, but when you get over 1000 Lines Comment code, is a little bit annoying. Thats why i didn't include Sass Libraries with Bower, otherwise i will get too much comment code.

Good i not the biggest Issue, you can Scroll down thats it - when no Sass Error come you will hold the Position in Sublime. With a compile error you need to scroll again. On the other side is a good tool for commenting code (would be perfect when it will document BEM and normal Elements g).

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 1, 2014

Member

To be honest and objective, I have not yet encountered situations where this is a blocking issue.
Except that you gotta like scrolling, plus maybe conflict with markers you could use for debugging.
This is due to the fact that SassDoc is young and I did not had the occasion to use it on a large project yet.
I'm also a bit worried for IE debugging sessions (7, 8, 9), where devtools are less than fancy (staying polite here), and weird bugs legion.

But as I said, that's maybe too premature.
Anyway glad we can talk about it here and collect feedback.

<conditional> As Hugo said, this would be more of a 2.0 thing. </conditional>

Projects are already adopting SassDoc at a quick pace, and changing the comments style have to be thoroughly planned.

I'm currently exploring tools to convert/strip comments.

Member

pascalduez commented Aug 1, 2014

To be honest and objective, I have not yet encountered situations where this is a blocking issue.
Except that you gotta like scrolling, plus maybe conflict with markers you could use for debugging.
This is due to the fact that SassDoc is young and I did not had the occasion to use it on a large project yet.
I'm also a bit worried for IE debugging sessions (7, 8, 9), where devtools are less than fancy (staying polite here), and weird bugs legion.

But as I said, that's maybe too premature.
Anyway glad we can talk about it here and collect feedback.

<conditional> As Hugo said, this would be more of a 2.0 thing. </conditional>

Projects are already adopting SassDoc at a quick pace, and changing the comments style have to be thoroughly planned.

I'm currently exploring tools to convert/strip comments.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 1, 2014

Member

Don't pay attention to the last notification you had where I go crazy with some weird Sass shit. It's pointless.

Member

HugoGiraudel commented Aug 1, 2014

Don't pay attention to the last notification you had where I go crazy with some weird Sass shit. It's pointless.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 1, 2014

Member

toto_sass_shit

Nice try actually, you should keep that gist for posterity !

Member

pascalduez commented Aug 1, 2014

toto_sass_shit

Nice try actually, you should keep that gist for posterity !

@kaelig

This comment has been minimized.

Show comment
Hide comment
@kaelig

kaelig Aug 1, 2014

Don't pay attention to the last notification you had where I go crazy with some weird Sass shit. It's pointless.

Good, I was going to ask you the contact info of your drug dealer. He's selling some pretty good stuff it seems.

More seriously, I may have found a good case for inline-comment support. This Sassmeister gist by Hugo: http://sassmeister.com/gist/55ed62df060dfb39b614

The output is cleaner thanks to // comments (so it's easier to understand exactly what Hugo wants to show), and would be easier to copy-paste back to your original code if SassDoc supported inline comments.

What are your thoughts?

kaelig commented Aug 1, 2014

Don't pay attention to the last notification you had where I go crazy with some weird Sass shit. It's pointless.

Good, I was going to ask you the contact info of your drug dealer. He's selling some pretty good stuff it seems.

More seriously, I may have found a good case for inline-comment support. This Sassmeister gist by Hugo: http://sassmeister.com/gist/55ed62df060dfb39b614

The output is cleaner thanks to // comments (so it's easier to understand exactly what Hugo wants to show), and would be easier to copy-paste back to your original code if SassDoc supported inline comments.

What are your thoughts?

@tjbenton

This comment has been minimized.

Show comment
Hide comment
@tjbenton

tjbenton Aug 6, 2014

You could just switch to DSS(Documented Style Sheets) which is set up in a very similar structure to what you guys already have. It seems like it would allow you to do exactly what you are wanting to do. It allows you to write either CSS(/**/) style comments and/or
inline(//) comments. All without forcing you to do anything special like ///, //*, or any of the other ones mentioned on here.

//
// @name Button
// @description Your standard form button.
// 
// @markup
//   <button>This is a button</button>
// 

If you don't want something to be documented you would do this

 // This inline comment has a space in front of it so it won't output anything.

By default it comes with 4 pre defined parsers or special tags. But the thing that is nice about it is the ability to write your own or even overwrite what they have. This would allow the community to come up with there own crazy ideas and contribute to SassDocs. If they don't want to add their own ideas they would still have the default template and default parsers that you would offer.

Here is how they do the @description
// Describe parsing a description
dss.parser("description", function(i, line, block, file){
  return line;
});

I'm sure you guys would be able to combine what you already have done with this or at the least see how they got it to work.

I like SassDoc and how it makes documenting sass really easy. That being said I like keeping all my documentation in one place, and currently I'm going crazy trying to find a tool that allows me to document functions, mixins, and variables like SassDoc does and also allows me to document the components that I'm using in my project. That shows you snippets of the code used to create those components as well as what the component actually looks like without having 700 css comments or updating separate documents.

I also find it very convenient to use github flavored markdown because it's something that is that the majority of developers know and love. They have great documentation about it. For those developers who have yet to discover github they probably aren't on the level they need to be to start using nodejs, installing packages, and using the command line, grunt, or gulp. (IMO)

Hope this helps.

tjbenton commented Aug 6, 2014

You could just switch to DSS(Documented Style Sheets) which is set up in a very similar structure to what you guys already have. It seems like it would allow you to do exactly what you are wanting to do. It allows you to write either CSS(/**/) style comments and/or
inline(//) comments. All without forcing you to do anything special like ///, //*, or any of the other ones mentioned on here.

//
// @name Button
// @description Your standard form button.
// 
// @markup
//   <button>This is a button</button>
// 

If you don't want something to be documented you would do this

 // This inline comment has a space in front of it so it won't output anything.

By default it comes with 4 pre defined parsers or special tags. But the thing that is nice about it is the ability to write your own or even overwrite what they have. This would allow the community to come up with there own crazy ideas and contribute to SassDocs. If they don't want to add their own ideas they would still have the default template and default parsers that you would offer.

Here is how they do the @description
// Describe parsing a description
dss.parser("description", function(i, line, block, file){
  return line;
});

I'm sure you guys would be able to combine what you already have done with this or at the least see how they got it to work.

I like SassDoc and how it makes documenting sass really easy. That being said I like keeping all my documentation in one place, and currently I'm going crazy trying to find a tool that allows me to document functions, mixins, and variables like SassDoc does and also allows me to document the components that I'm using in my project. That shows you snippets of the code used to create those components as well as what the component actually looks like without having 700 css comments or updating separate documents.

I also find it very convenient to use github flavored markdown because it's something that is that the majority of developers know and love. They have great documentation about it. For those developers who have yet to discover github they probably aren't on the level they need to be to start using nodejs, installing packages, and using the command line, grunt, or gulp. (IMO)

Hope this helps.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Aug 24, 2014

Member

@tjbenton I am sorry I didn't give any feedback earlier. Unless we find it extremely attractive, we won't trade our parser for another one.

@pascalduez Please give us a hint about this tool to convert different types of comments.

Member

HugoGiraudel commented Aug 24, 2014

@tjbenton I am sorry I didn't give any feedback earlier. Unless we find it extremely attractive, we won't trade our parser for another one.

@pascalduez Please give us a hint about this tool to convert different types of comments.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Aug 25, 2014

Member

I had good hopes about node-comments for converting different comment styles back and forth. Sadly, at the time of testing it was not working properly. I though of starting my own lib, or maybe we should contribute/patch that one.

Then there are comments removers, which is not ideal, but might fit into Sass libs providing dist files.
strip-comments, grunt-stripcomments

Member

pascalduez commented Aug 25, 2014

I had good hopes about node-comments for converting different comment styles back and forth. Sadly, at the time of testing it was not working properly. I though of starting my own lib, or maybe we should contribute/patch that one.

Then there are comments removers, which is not ideal, but might fit into Sass libs providing dist files.
strip-comments, grunt-stripcomments

@HugoGiraudel HugoGiraudel changed the title from C style comments in CSS output to Add ability to use inline comments Sep 8, 2014

@ezekg

This comment has been minimized.

Show comment
Hide comment
@ezekg

ezekg Sep 11, 2014

If anybody gets that annoyed with it, they can disable multiline comments completely with a little Ruby magic. I know I got annoyed with it, especially when running tests and needing to read the output.

class Sass::Tree::Visitors::Perform < Sass::Tree::Visitors::Base
    # Removes all comments completely
    def visit_comment(node)
        return []
    end
end

Just chunk that in your config.rb file if you're using Compass.

Maybe you guys could add a silence function that authors can use to mute their doc blocks?

ezekg commented Sep 11, 2014

If anybody gets that annoyed with it, they can disable multiline comments completely with a little Ruby magic. I know I got annoyed with it, especially when running tests and needing to read the output.

class Sass::Tree::Visitors::Perform < Sass::Tree::Visitors::Base
    # Removes all comments completely
    def visit_comment(node)
        return []
    end
end

Just chunk that in your config.rb file if you're using Compass.

Maybe you guys could add a silence function that authors can use to mute their doc blocks?

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Sep 13, 2014

Member

Just pasting @nex3 comment from sass/sass#1432 for the records.

I'm fine with preserving the double-star, since it's a well-known convention (although honestly I think using CSS comments rather than single-line comments for documentation is a misuse).

Member

pascalduez commented Sep 13, 2014

Just pasting @nex3 comment from sass/sass#1432 for the records.

I'm fine with preserving the double-star, since it's a well-known convention (although honestly I think using CSS comments rather than single-line comments for documentation is a misuse).

@HugoGiraudel HugoGiraudel modified the milestones: 2.0, 1.9 Sep 20, 2014

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 22, 2014

Member

@FWeinb has made some nice progress on this issue. We need to find a way to describe a poster comment though. One solution would be:

//**
// Poster
//**

Keeping the double-stars. What do you think?

Member

HugoGiraudel commented Sep 22, 2014

@FWeinb has made some nice progress on this issue. We need to find a way to describe a poster comment though. One solution would be:

//**
// Poster
//**

Keeping the double-stars. What do you think?

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Sep 22, 2014

Member
//**
// Poster
//**

That looks completely fine to me.

What about the /// kinda standard. Do we decided not to implement it ?

Member

pascalduez commented Sep 22, 2014

//**
// Poster
//**

That looks completely fine to me.

What about the /// kinda standard. Do we decided not to implement it ?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 22, 2014

Member

Good point. We could decide to use /// for docs. This would probably prevent some greedy grabbing while keeping docs invisible in output. What do you say @SassDoc/owners?

Member

HugoGiraudel commented Sep 22, 2014

Good point. We could decide to use /// for docs. This would probably prevent some greedy grabbing while keeping docs invisible in output. What do you say @SassDoc/owners?

@HugoGiraudel HugoGiraudel removed the Maybe label Sep 22, 2014

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 22, 2014

Member

To wrap this up:

  • Normal SassDoc comments would be /** */ and ///
  • Poster comments would be /** **/ and ///**

Am I right here?

Member

FWeinb commented Sep 22, 2014

To wrap this up:

  • Normal SassDoc comments would be /** */ and ///
  • Poster comments would be /** **/ and ///**

Am I right here?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 22, 2014

Member

Basically. What do you say?

Member

HugoGiraudel commented Sep 22, 2014

Basically. What do you say?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 22, 2014

Member

Yeah I would like that.

Member

FWeinb commented Sep 22, 2014

Yeah I would like that.

@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Sep 22, 2014

Member

The "normal" comments are standard, so I like it.

The poster comments looks kinda odd, but I don't know any convention here so I don't really have an opinion on this.

Member

valeriangalliat commented Sep 22, 2014

The "normal" comments are standard, so I like it.

The poster comments looks kinda odd, but I don't know any convention here so I don't really have an opinion on this.

@ezekg

This comment has been minimized.

Show comment
Hide comment
@ezekg

ezekg Sep 22, 2014

Would /// cause problems with commented lines that look like this?

// // Previous comment
// div { ... }

My editor will do that when commenting out a selection that previously had comments in it. I'm guessing the added space between the forward slashes would prevent SassDoc from parsing it.

ezekg commented Sep 22, 2014

Would /// cause problems with commented lines that look like this?

// // Previous comment
// div { ... }

My editor will do that when commenting out a selection that previously had comments in it. I'm guessing the added space between the forward slashes would prevent SassDoc from parsing it.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 22, 2014

Member

@ezekg That is perfectly fine.

@SassDoc/owners
I just published scss-comment-parser@0.4.0-pre4. So if you guys want to test this just run:
npm install scss-comment-parser@0.4.0-pre4

I updated it to pre4. Changes are that instead of ///** we are now using //// at least (4) slashes.
With this change you can build poster comments like this:

///////////////////////////////////////
///          Poster Comment         ///
///////////////////////////////////////
Member

FWeinb commented Sep 22, 2014

@ezekg That is perfectly fine.

@SassDoc/owners
I just published scss-comment-parser@0.4.0-pre4. So if you guys want to test this just run:
npm install scss-comment-parser@0.4.0-pre4

I updated it to pre4. Changes are that instead of ///** we are now using //// at least (4) slashes.
With this change you can build poster comments like this:

///////////////////////////////////////
///          Poster Comment         ///
///////////////////////////////////////
@valeriangalliat

This comment has been minimized.

Show comment
Hide comment
@valeriangalliat

valeriangalliat Sep 22, 2014

Member

I like this new kind of poster comments. :)

Member

valeriangalliat commented Sep 22, 2014

I like this new kind of poster comments. :)

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Sep 22, 2014

Member

First test with inline comments.
https://github.com/pascalduez/SassyIcons/tree/test-inline-comments

The poster comments does not seem to work properly.
I tried:

////
/// @group config
////
////
//// @group config
////
///**
/// @group config
///**

Also tried adding a description.

@FWeinb what's the syntax at the end ?

Member

pascalduez commented Sep 22, 2014

First test with inline comments.
https://github.com/pascalduez/SassyIcons/tree/test-inline-comments

The poster comments does not seem to work properly.
I tried:

////
/// @group config
////
////
//// @group config
////
///**
/// @group config
///**

Also tried adding a description.

@FWeinb what's the syntax at the end ?

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 22, 2014

Member

Four slashes on the first line, four slashes on the list line, any number in the comment itself.

Member

HugoGiraudel commented Sep 22, 2014

Four slashes on the first line, four slashes on the list line, any number in the comment itself.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 23, 2014

Member

@pascalduez
Sorry there was an issue with that in pre4.
Run npm install scss-comment-parser@0.4.0-pre5 and test it again.

Member

FWeinb commented Sep 23, 2014

@pascalduez
Sorry there was an issue with that in pre4.
Run npm install scss-comment-parser@0.4.0-pre5 and test it again.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 23, 2014

Member

👍

Member

FWeinb commented Sep 23, 2014

👍

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Sep 23, 2014

Member

npm install scss-comment-parser@0.4.0-pre5

SassyIcons Seems all fine.
SassyFilters Seems all fine.

Member

pascalduez commented Sep 23, 2014

npm install scss-comment-parser@0.4.0-pre5

SassyIcons Seems all fine.
SassyFilters Seems all fine.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 24, 2014

Member

We still have some time to get things running. I'll release 1.8 tomorrow.

Member

HugoGiraudel commented Sep 24, 2014

We still have some time to get things running. I'll release 1.8 tomorrow.

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 24, 2014

Member

This should basically be ready.

Member

FWeinb commented Sep 24, 2014

This should basically be ready.

@pascalduez

This comment has been minimized.

Show comment
Hide comment
@pascalduez

pascalduez Sep 24, 2014

Member

Yeah, I will keep on testing a bit I guess.

But still, already freakin' great.

Member

pascalduez commented Sep 24, 2014

Yeah, I will keep on testing a bit I guess.

But still, already freakin' great.

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 25, 2014

Member

Can we close it @FWeinb?

Member

HugoGiraudel commented Sep 25, 2014

Can we close it @FWeinb?

@FWeinb

This comment has been minimized.

Show comment
Hide comment
@FWeinb

FWeinb Sep 25, 2014

Member

I just updated scss-comment-parser to version 0.4.0 so this can be closed.

Member

FWeinb commented Sep 25, 2014

I just updated scss-comment-parser to version 0.4.0 so this can be closed.

@FWeinb FWeinb closed this Sep 25, 2014

@HugoGiraudel

This comment has been minimized.

Show comment
Hide comment
@HugoGiraudel

HugoGiraudel Sep 29, 2014

Member

We should not forget to update the file-level annotations page from the docs to explain how to write a poster with inline comments. I'll do it.

Member

HugoGiraudel commented Sep 29, 2014

We should not forget to update the file-level annotations page from the docs to explain how to write a poster with inline comments. I'll do it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment