Open renestalder opened 8 years ago
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:
@styleguide
definitionI 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.
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.
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.
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.
@styleguide
definitionExactly, 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.
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 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.
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.
<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:<li>something</li>
in my example) and when required a @markupWrapper can be defined (<ul>{markup}</ul>
in my example)@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 :)
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 aStyleguide 1.1.2
orStyleguide 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 withMarkup: 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.
@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.@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.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.