Feature request: Extend the syntax about postcss-style-guide HOT 8 OPEN

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.

from postcss-style-guide.

@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.

from postcss-style-guide.

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.

from postcss-style-guide.

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
*/

from postcss-style-guide.

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.

from postcss-style-guide.

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?)

from postcss-style-guide.

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

from postcss-style-guide.

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

from postcss-style-guide.