Support for Sass variables and documenting BEM/OOCSS hierarchy/relationships about sassdoc HOT 6 CLOSED

Hello Aaron and thanks a lot for taking the time to have a look.

First, let me remind this project is veryyyyyy young. I have only worked on it for a couple of hours with the help of @valeriangalliat, and I'd never written a single line of Node before it, so it's pretty much a crash test here! That being said, since https://github.com/eoneill/sassdoc has been dead for like 2 years... I thought it might be a good idea to give it a try.

Anyway.

I am willing to include variable documentation. I think it's a perfectly valid request. I'd like to see something like this:

// @var {type} name (value) - description
$var: my variable;

This would be a good way to keep in sync with parameter parsing but I am not convinced with the value being between curved braces. I feel like it should have a stronger place in the line. We'll have to think about it.

I need to implement @example but for that, I need to turn the whole thing into a real parser, and not some shitty regular expressions.

Eventually I want to end up with this:

// @example
//    clamp(10, 1, 5)
//    // -> 5

Or something like that.

Fully okay with @since. Will be very easy to add by the way.

I'll update this comment when I get time.

from sassdoc.

Cool, thanks Hugo!

from sassdoc.

Hi all,

Thanks Aaron for all these suggestions! This will bring SassDoc to a new level for sure - and Hugo was just searching improvements ideas. :)

Variables

About the variable documentation, I don't see the need to include the variable name and default value in the docstring. The actual variable declaration just below is giving the name and default value, so why not just display it (like the function/mixin signatures)?

// @var {type} description
$var: default value;

I think we could epurate @param in the same way. Since there may be multiple @params it's more readable to keep the name, but the default value can still be deducted from the signature.

Maybe the @public annotation can be ommited too, since we can see the !global in the variable signature.

Maps

It's interesting to add a documentation format for (nested) maps. I don't like the JSDoc way of doing this:

/**
 * @param {Object} options
 * @param {String} options.foo
 * @param {Number} options.bar
 */

I'd see something more like YAML (this is not valid YAML though):

// @var {map}
//   base:
//     default: {type} description
//       text: {type} description
//       bg: {type} description
//       bd: {type} description
//     success: {type} description
//   ... 
$panel: (...);

But I'm not really sure about it, it will be really verbose.

Another possibility is to add comments directly in the map declaration:

// @var {map} description
$panel: (
  'base': (
    'default': ( // @key {type} description
      'text': $gray-dark, // @key {type} description
      'bg': #fff, // @key {type} description
      'bd': #ddd, // @key {type} description
    ),
  ),
);

This would require to parse the whole map to extract the structure, but it's more lightweight to define.

Otherwise, if we display the real variable declaration in the documentation, simple comments like above even without the @key would be sufficient to understand the purpose of the commented keys. For example the Kohana framework's API browser displays the full source code of a function below the formatted docblock, and I find this really handy. A similar thing for variable declarations including comments can be sufficient.

Examples

The @example annotation is a bit tricky for the syntax highlighting. We can want it to highlight Sass or HTML depending on the cases. I think it's fair to assume an @example on a mixin or function will be in Sass, but will contain HTML when applied on a CSS class.

If needed, an optional lang attribute could be added after @example to set the right syntax highlighting, but I don't really see an use case for this (if the contextual syntax above is implemented).

Also since the "long description" is interpreted as Markdown, it's also possible to define the code samples within the description instead of adding @example. What do you think?

Meta

@usedin is interesting, but I'm not sure about the naming. @see would be more standard, but the semantic is not exactly the same.

@support should be @supports to keep it consistant with @returns, @throws, @depends, etc.

BEM

I like the idea of documenting BEM classes.

Like the name and value for variables, we can also get the class name by looking the line after the docblock, it's redundant to add it after the annotation. But maybe it can be tricky to find it in the selector for more complex cases?

from sassdoc.

@valeriangalliat thanks for taking a look!

Variables
Agreed on all points. the name of the var shouldn't need to be included in the docblock

Maps
I think adding the @key declaration directly in the map is a more ideal solution

Examples
This is low priority IMO - I'm much more interested in the @depends / BEM documentation.

Meta
This is also low priority - but i'm cool with changing @support to @supports.

BEM
This is the piece that the SassDocJS tool demonstrates nicely - but it is a poorly coded solution, and I've yet to be able to get it up and running in a local environment.

I think the base class would still need to be declared in the docblock as I showed in my example - but what you're saying is that the "name" could be omitted for the others if the base class was used as reference like so?

// @base panel
.panel { }

// @element
.panel-body {}

In this example - are you saying that the .panel-body class would be reference-able / defined as @element panel-body since it starts with the class defined as a @base?

What I mean by "reference-able" - is... will the docs be able to demonstrate a linked hierarchy and understand the difference, for instance between a @element (nested within the @base) and a @modifier (additional context for a @base OR @element)?

If the referential integrity can still remain simply by inferring that an @element or @modifier with no name listed should simply be stored based on the line immediately after the docblock... I think that would work fine!

Let me know if that makes sense.

from sassdoc.

Hello.

Okay, so I got cut yesterday night. Let me come back to what I was saying.

@var

Will be implemented under the following syntax:

// @var {type} - Description
$variable: my variable;

A few notes:

• The hyphen will be optional
• A !global flag will make the variable public, else it will be private (scoped)
• Map won't have any special doc at first, it will eventually come later

@example

I want to implement this, but as I said I need a real parser for this. Regular expressions won't do the trick. That being said, writing a parser is complicated, but I'll give it a try.

For now, I suggest you join them in the description since it is being parsed in Markdown. I haven't tried but I'd say that:

// Here is the description or whatever
//    clamp(10, 0, 5);
//    -> 5

... should work.

@usedin

I like the idea but not the name. Perhaps @see would be enough for me. That being said, I want to have something like that so I'm okay.

@SInCE

Agreed. Will be implemented.

@supports

I am not willing to add this. This is very anecdotal and should belong in the description in my opinion. Unless someone has a very strong reason to add such a feature, this is a nope.

Documenting BEM

Okay, I like that. Although I don't think it's possible to do that with regular expressions right now so until we have a dedicated parser, this probably won't work.

I have hard time seeing the difference between @depends and @requires. As far as possible, I'd like to keep only one, unless both are serving strictly different purposes.

I'll open separated issues for all this stuff. Please move discussion to specific issues.

from sassdoc.

@hugogiraudel awesome - thanks!

from sassdoc.