Feature Request: Multi-line descriptions / Loop

[m5o]

First, this project is amazing!! The last weeks i played with different styleguide tools (grunt-styleguide, kss-node, styledocco). I am so happy that i found this repository.

On my testing trip I found one key feature from kss-node very interesting. Read the part on Multi-line descriptions.

In short - in their markup section they use the {$modifiers} keyword as a spacer. The next few lines specify the attributes. The syntax is like a list.

This is a example from the kss-node/demo

// Buttons
//
// A majority of buttons in the site are built from the same base class.
// 
// Markup:
// <a href="#" class="button {$modifiers}">Link Button</a>
// <button class="button {$modifiers}">Button Element</button>
// <input type="button" class="button {$modifiers}" value="input[type='button']"/>
// 
// .primary             - Indicate that the button is the primary feature of this form.
// .remove              - Indicate that the button will remove a feature, or other negative connotations.
// :hover               - Highlight the button when hovered.
// :disabled            - Make the button change appearance to reflect it being disabled.
// :active              - "Press" the button down when clicked.

The processor loops thought the markup code and add the attributes for $modifiers.

View the result It is cleaner, less duplication and easy to see different variations of an element.

or watch this kss-node-template with more multi-line descriptions and examples.

What do you think about this feature?
This is an open discussion. Is this possible with handlebars? Useful / Useless...

Greets,
m5o

[winstromming]

Thanks for the suggestion. I understand exactly why people might want this, but it's also what I attempted to move away from with Sassdown. When you begin defining very specific markup requirements, it's no longer flexible. KSS is very good at what KSS does - but Sassdown aims to be a little more freeform with the commenting syntax (ie. strictly full Markdown).

What I am currently investigating is the grouping and displaying of variables from the SASS source, if they exist. But that doesn't directly tackle your suggestion. However, it's not a path I'm currently looking to go down. Future release, maybe. Optional syntax, maybe. Right now? No.

[m5o]

ok thanks for your words. What about find conventions and not breaking Markdown syntax. Here I am on your side strictly support markdown syntax. This example with an h3 and a simple bullet list.

    <a href="#" class="button `$modifiers`">Link Button</a>
    <button class="button `$modifiers`">Button Element</button>
    <input type="button" class="button `$modifiers`" value="input[type='button']"/>

### Variations
* .primary      - Indicate that the button is the primary feature of this form.
* .remove      - Indicate that the button will remove a feature

I've noticed also the guys from github use simple bullet list. Check out github.com/styleguide

[winstromming]

I'm going to close this issue, as to some extent it defers to #38