Feature request: Extend the syntax

Thanks to a friendly Twitter reply in my search of a style guide tool that handles CSS Selector Level 4 variables, I found your repository and like what you are doing.

Since I started using KSS-Node some weeks ago, a very popular style guide generator, I would like to share my experience. I already started building themes for kss-node styleguide, so I might had some deeper look into it. I didn't use postcss-style-guide before, so my knowhow comes out of your documentation.

First of all, KSS itself just defines the way of documenting CSS. Out of the box, it's more like a spec for the syntax. Then it includes Ruby gems to generate the style guides built with the specified syntax, but it's not needed.

kss-node brings those features to the node environment, making it possible to build style guides without the need of ruby.

So the important point here is, the documentation just works and makes sense even without generating a style guide. This is an important point because in programming, documenting your functions an classes are not meant to generate documentation in a first instance.

Additionally if have features to control the output of a possible styleguide. For example, I can add a weight property to order the output, or I can add a Styleguide 1.1.2 or Styleguide Components.Buttons to group my definitions in chapters, which is very handy. I'm also able to write markup inline like in postcss-style-guide, but can also add it to a .html file and reference it with Markup: mymarkup.html which is kind of a must for big HTML structures.

So I would like to give some feature ideas for your library since I'm very interested documenting my projects which all use CSS Selector Level 4 stuff.

Drop the @styleguide definition in the header. It's repeating and doesn't add value for the documented piece of code itself, so it shouldn't exist or at least not placed at the start. It's kind of secondary annotation, similar to Angular's @nginject. You're also able to find styleguide comments by searching for the @title annotation.
Standardize the syntax. You use @title for the title, so I expect using the same for the description e.g. @description. Or do it like kss and drop any of those annotation tags. But to be honest, I like your solution with the @ chars because it's identical to most programming languages' documentation syntax.
Add grouping and sort options. Because we need some kind of control to bring structure into the style guide to go from abstract to concrete design examples e.g. from single components to complex patterns and layout examples.
Add states to the documentation syntax. Instead of repeating a component in different states, it would be quite easier to add the different modificator classes to the documentation and automatically generate the component in it's different states. See the output example here and the syntax of KSS here.

The main reason why I'm coming up with this in your repository is, the KSS repository seems to have a lack of maintainers and pull request are kind of ignored at the moment, so chances are small to extend it for CSS Selector Level 4 variables.

Thanks for reading and your work and I hope you can use some of my inputs.

Hi, @renestalder . Thank you for your report and sharing your knowhow about building style guide :)

Drop the @styleguide definition in the header.

We can use some annotations (e.g. @doc) to define the document as well as @styleguide. I'm sorry, it's not written in README. See also here. Or you means, annotations to define documents (@styleguide, @doc and so on) don't neet, right? (so, we can use @title instead of them)

I expect using the same for the description e.g. @description.

It's a nice idea! But I would like to know why it's not good to define explanatory text of its component by paragraph in markdown.

/*
@doc

@title Components

@description description of the component
*/

You means, the above code is better than the following code?

/*
@doc

@title Components

description of the component
*/

Add grouping and sort options.

Yeah, just I also thought so :) Do you have any idea to define the order? I think the following annotations syntax. We can sort documents in ascending sequence of @chapter.

/*
@doc

@title Component

@chapter 1.0.0
*/

Add states to the documentation syntax.

Now, I write documentation comments for postcss-style-guide to specify its state as below.

/*
@doc

@title Component

Normal:

<div class="component">
  markup for this component
</div>

Active:

<div class="component component--active">
  markup for this component
</div>
*/

Should I use a new annotation to define its state? (e.g. @state state name)

May I ask if you understand what I mean? So sorry, I"m not good at English. Thanks.

Thanks for your reply, @morishitter.

To clarify my points:

Drop the `@styleguide` definition

I guess, the only reason why you're adding an @styleguide annotation is to search for CSS documentation. But the documentation also only works with an @title tag. So in my opinion, the @styleguide or @doc is pointless, because you could also look up for the @title annotations to know if there exists a documentation.

Standardize the syntax

I mean, we want to write consistent documentation. So when we already have to use an @title definition, it's not clear to me, why the description doesn't need an annotation too.

This looks far more consistent to me:

/*
@doc

@title Components

@description description of the component
*/

To think this further, this would also make sense for me:

/*
@doc

@title Components

@description description of the component

@markup
<div class="component">
  markup for this component
</div>
*/

Here's just another example how KSS is doing it. They only use an annotation for the markup and the category in the styleguide. This isn't consistent too.

/*
Rating Button

A button suitable for giving stars to someone.

:hover             - Subtle hover highlight.
.stars-given       - A highlight indicating you've already given a star.
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
.disabled          - Dims the button to indicate it cannot be used.

Markup:
<button class="rating-button {modifier}"></div>

Styleguide 2.1.3.
*/
rating-button.star{
  ...
}
rating-button.star.stars-given{
  ...
}
rating-button.star.disabled{
  ...
}

They took the concept, that the first line have to be the title, all following text belongs to the description.

My point is: We could do better and annotate all or nothing. I would annotate all like you would do in most programming languages and Jsdoc.

Add grouping and sort options

Your idea is fine as long it's optional. I would use @styleguide instead of @chapter (or make both valid), because this annotation is just for the generated styleguide while any other part of the documentation in the comment is also valid without having a generated HTML styleguide.

Add states to the documentation syntax

While you can define states in postcss-style-guide currently by repeating the whole markup for every state, it would be easier to write the markup only once.

So here's the example of KSS again. You write your markup once, add a modifier placeholder – which can be defined in the command line or config – and the generator will output an example for every state.

/*
Rating Button

A button suitable for giving stars to someone.

:hover             - Subtle hover highlight.
.stars-given       - A highlight indicating you've already given a star.
.stars-given:hover - Subtle hover highlight on top of stars-given styling.
.disabled          - Dims the button to indicate it cannot be used.

Markup:
<button class="rating-button {modifier}"></div>

Styleguide 2.1.3.
*/
rating-button.star{
  ...
}
rating-button.star.stars-given{
  ...
}
rating-button.star.disabled{
  ...
}

In postcss-style-guide, this could look like this:

/*
@title Rating Button

@description A button suitable for giving stars to someone.

@state :hover - Subtle hover highlight.
@state .stars-given - A highlight indicating you've already given a star.
@state .stars-given:hover - Subtle hover highlight on top of stars-given styling.
@state .disabled - Dims the button to indicate it cannot be used.

@markup
<button class="rating-button {modifier}"></div>

@styleguide 2.1.3
*/

@renestalder Thanks, I understood your opinion clearly.

Here is my opinion to each proposals.

Drop the `@styleguide` definition

Exactly, annotations to define the document like @styleguide are not necessary. Including me, most people who build their style guide are using with @title to set its component's name.

Standardize the syntax

Now, the parts of comments are parsed as Markdown, and it have semantics, e.g. normal text means the paragraph, and string around ````` means a code block. I think, Markdown in itself have semantics and standarized.

Add grouping and sort options

I have two idea. The first is using @chapter.

@chapter 1.0.0

The string after @chapter is three-digit number. The upper number is its category number, and postcss-style-guide sort documents according to its two lower number.

The second idea is using to annotations that specify its category name and its order.

@category Base
@order 1

In this idea, we can set the name of its category. I think,the values of @order don't appear in the document.

Add states to the documentation syntax

It seems nice, it's bored to repeat HTML code each states. But I think, it's hard to implement by the syntax that you proposed.

What do you think about the following code to specify their states.

e.g.

/*
@title Rating Button

@description A button suitable for giving stars to someone.

@state-button .stars-given - A highlight indicating you've already given a star.
@state-button .stars-given:hover - Subtle hover highlight on top of stars-given styling.
@state-button .disabled - Dims the button to indicate it cannot be used.

@state-icon .icon--large - large icon
@state-icon .icon--small - small icon

@markup
<button class="rating-button {state-button}">
  <span class="icon {state-icon}></span>
</button>

@styleguide 2.1.3
*/

If HTML markup has the complicated structure, it's difficult to specify all modifies by only one annotation (@state). It is able to solve this probrem by the above code.

Now, the parts of comments are parsed as Markdown, and it have semantics, e.g. normal text means the paragraph, and string around ``` means a code block. I think, Markdown in itself have semantics and standarized.

I didn't mean this part. I just meant using @ tags overall or none of them instead of using them only for some parts.

@category Base
@order 1

That's great. Quite identical to KSS and I found KSS way easy to use.

/*
@title Rating Button

@description A button suitable for giving stars to someone.

@state-button .stars-given - A highlight indicating you've already given a star.
@state-button .stars-given:hover - Subtle hover highlight on top of stars-given styling.
@state-button .disabled - Dims the button to indicate it cannot be used.

@state-icon .icon--large - large icon
@state-icon .icon--small - small icon

@markup
<button class="rating-button {state-button}">
  <span class="icon {state-icon}></span>
</button>

@styleguide 2.1.3
*/

Here's is one problem for me: If the icon really has it's own states, it's a own component for me and needs it's own documentation. But if it can only be used with the button surrounding it, I would define my CSS like this:

.rating-button__icon-large .icon { ... }

Thus setting the states on the button itself:

/*
@title Rating Button

@description A button suitable for giving stars to someone.

@state .stars-given - A highlight indicating you've already given a star.
@state .stars-given:hover - Subtle hover highlight on top of stars-given styling.
@state .disabled - Dims the button to indicate it cannot be used.
@state .rating-button__icon-large - large icon
@state .rating-button__icon-small - small icon

@markup
<button class="rating-button {state}">
  <span class="icon"></span>
</button>

@styleguide 2.1.3
*/

or as an alternative, working with some kind of references:

/*
@title Icon

@description An icon

@state .icon-large
@state .icon-small

@markup
<span class="icon {state}></span>

@styleguide 3.1.0
*/

/*
@title Rating Button

@description A button suitable for giving stars to someone.

@state .stars-given - A highlight indicating you've already given a star.
@state .stars-given:hover - Subtle hover highlight on top of stars-given styling.
@state .disabled - Dims the button to indicate it cannot be used.

@markup
<button class="rating-button {state}">
  {{ styleguide 3.1.0 }}
</button>

@styleguide 2.1.3
*/

Maybe it makes sense to use some alternate syntax based on CSS class nesting of Selector Level 4 proposal (http://tabatkins.github.io/specs/css-nesting/) to define the states and their nesting states.

I didn't mean this part. I just meant using @ tags overall or none of them instead of using them only for some parts.

Thank you for your proposal. Take time to think to me.

If the icon really has it's own states, it's a own component for me and needs it's own documentation.

Exactly.

@markup
<button class="rating-button {state}">
  {{ styleguide 3.1.0 }}
</button>

The syntax to import the other markup in the document seems nice.

@stylguide annotation means its order in the document? (Is it the same as @category and @order, or @chapter?)

Either @styleguide or @category or @chapter, whatever solution you would choose.

Hi @morishitter @renestalder,

I like the module and will be using it in a project, for which I am building a custom theme tailored for our use case.

I would also welcome the enhancements discussed here.

drop the @style definition
standardise the syntax (preferably always with an @marker style)
add group and sorting option. Most importantly grouping, sorting as second wish.
add states to document syntax. A single @state would satisfy my current use case, but morishitter's suggestion with @state_a, @state_b... would be more flexible, but perhaps more complex to implement.
Two additions/suggests to this list:
- allow custom @markers: any @customMarker type marker at the start of a line and after an empty line could be included in the json for use in the template as an array "customMarker". This way things like @changeLog could be added. It would be up to the developer to cater for this in a custom template.
- Where markup for element and example is the same, use the same markup snippet in css comment: Currently to show the example markup, the markup needs to be repeated indented 4 spaces after the markup used to show the element. This is useful when for example the element is a list item. In this case the first markup would be <ul><li>something</li></ul> and the second indented 4 spaces just <li>something</li>. However in most cases these are identical. Not only does it increase the work, it is also not DRY. A developer must always be careful to keep both versions synchronised. I suggest 2 possible solutions:
- If the second 4 space indented markup is not present, always use the first for the example
- OR similar to KSS-node the @markup is always the clean markup (<li>something</li> in my example) and when required a @markupWrapper can be defined (<ul>{markup}</ul> in my example)
- also in both cases it would be useful if in the template, along with map.html which has both prepared versions, these could be separately available: eg. map.html (complete) map.element (element as rendered in html with optional wrapper) and map.code (escaped, code of just the markup). This would allow template developers maximum flexibility.

@morishitter Thanks for the great work and module! I hope this is of use to you.

@bird-cage Thank you for your opinion! I'll confirm it :)

matype / postcss-style-guide