Hi Chris, thanks for all your work on Compass and SASS. Great tools.
I ran across this project while trying to decide on documentation standards for my project mixins. I come from a Drupal background where we have extremely strict standards around code documentation, so writing some "SASSdoc" seemed like the most natural thing in the world to me. However I wanted to try to use the same standards (if any) as other SASS users. So far it doesn't look like there's really a standard yet, so I wanted to make some suggestions in your implementation.
I'm most familiar with PHPdoc, since it's what Drupal uses, but it's based on JavaDoc. There are a number of other spinoffs too:
In all situations, parameters are specified with the @param directive, not @parameter. For the sake of consistency with these other docblock standards, it would be good if SASSdoc followed suit. I know this project is only a parser, but as it's the source I found when Googling for "SASSdoc" it would be great to set the standard properly.
All three of these samples also use "Loud" comments (since those languages don't have Quiet comments), but again it might be good to adopt them by default for consistency.
carwin
commented
11 years ago
Hi Chris, thanks for all your work on Compass and SASS. Great tools.
I ran across this project while trying to decide on documentation standards for my project mixins. I come from a Drupal background where we have extremely strict standards around code documentation, so writing some "SASSdoc" seemed like the most natural thing in the world to me. However I wanted to try to use the same standards (if any) as other SASS users. So far it doesn't look like there's really a standard yet, so I wanted to make some suggestions in your implementation.
I'm most familiar with PHPdoc, since it's what Drupal uses, but it's based on JavaDoc. There are a number of other spinoffs too:
http://en.wikipedia.org/wiki/Javadoc http://en.wikipedia.org/wiki/Phpdoc http://en.wikipedia.org/wiki/Jsdoc
In all situations, parameters are specified with the
@paramdirective, not@parameter. For the sake of consistency with these other docblock standards, it would be good if SASSdoc followed suit. I know this project is only a parser, but as it's the source I found when Googling for "SASSdoc" it would be great to set the standard properly.All three of these samples also use "Loud" comments (since those languages don't have Quiet comments), but again it might be good to adopt them by default for consistency.