Enable hierarchy in documented modules

[webholics]

I like the syntax of DSS very much, especially when compared to KSS ( http://warpspire.com/kss/) because its more strict. But KSS has the advantage that it allows to express a hierarchical relationship between modules (through Styleguide X.X.... annotation). This makes it possible to group modules into logical chunks.

It would be nice to have some kind of syntactic sugar to express hierarchical relationships in DSS, too.

What I don't like in KSS is that the explicit numbering of the annotations is given by the author through Styleguide 1.5.. This leads to regular refactoring in bigger projects.

One possible solution would be to just allow the annotation of the group depth in which the module should sit, e.g.

//
// @name Buttons
// @description There are multiple button types.
// @depth 1
// 

... CSS code

//
// @name Regular Button
// @description Your standard form button.
// @depth 2
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button</button>
// 

... CSS code

//
// @name Special Button
// @description A special button.
// @depth 2
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button <strong>with a fancy label</strong></button>
// 

... CSS code

The above code should then generate a hierarchical JSON output similar to:

{
  "name": "Buttons",
  "description": "There are multiple button types.",
  children: [{
    "name": "Regular Button",
    "description": "Your standard form button.",
    ...
  }, {
    "name": "Special Button",
    "description": "A special button",
    ...
  }]
}

[darcyclarke]

@webholics the need to have nesting/groupings makes a lot of sense. That said, I don't like the idea of nesting in the JSON output (it starts to look like nested callbacks, which are ugly). To keep things nice and shallow, I've contemplated the idea of a default children, parents or extends attribute for comment blocks. The problem with that is that you would then need identifiers, which DSS doesn't enforce right now.

The name property may work, although I'd rather create these identifiers dynamically and utilize preprocessors native extending or nesting capabilities to create those relationships. This requires more work on the parser but it would keep your comment blocks clean and rely less on manual tracking of associations/inheritance.

For now, you can still accomplish this by writing comments similar to:

//
// @name Buttons
// @description There are multiple button types.
//

...

//
// @name Regular Button
// @description Your standard form button.
// @extends Buttons
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button</button>
//

...

//
// @name Special Button
// @description A special button.
// @extends Buttons
// 
// @state :hover - Highlights when hovering.
// @state :disabled - Dims the button when disabled.
// 
// @markup
//   <button>This is a button <strong>with a fancy label</strong></button>
//

...

And then use the grunt-dss library to write your own parser to map/group the children within the parent.

extends: function(i, line, block){
  // ...
}

[webholics]

Extending via @extend is quite a nice idea, simple and nice syntax
I don't like the idea to utilize preprocessor syntax because this makes you much more dependent on the preprocessor semantics. Writing CSS becomes hacky sometimes and that means sometimes you have to write your styles in a very specific way to provide expected browser support or nice fallbacks (e.g. utilizing Modernizr css classes: .csstransforms .myclass { ... }. It would be bad if a developer would have to also worry about breaking documentation in such cases.
That's why in my opinion it would be better to force explicit documentation via @extend.

[mishal]

+1

[darcyclarke]

Similar to #51, I may write a custom parser to show how this is done as it seems like it would be something people want to do. Not sure if I'll bake it into the defaults we provide just yet but we'll see.

[custa1200]

This has been around for about a year now @darcyclarke. Are you still actively looking at improving DSS?