Why use StyleDoc?

A boring intro about code documenting in general… (skip)

In coding world, if you make a project that should be further maintained, you should document the code you write within that project. Because if you don't, that code could be very difficult to understand, reuse, improve or fix for your team-mate or even for yourself after a few months.

One good way of program code documenting is to provide docblocks in the beginning of the class, method, etc. Such kind of docblocks describe what does the thing do, and how you can use it. That includes describing the interface of the thing: accepted arguments and their types, returned value, code examples, etc.

One of the most popular documenting standards were created for Java, called Javadoc. The principles and syntax for this format (/**-based docblocks, @-named tags, etc.) provided a base for similar standards for another languages, such as phpDocumentor and JSDoc. So, Javadoc documenting standard became (in some way) cross-language, widely used and easily comprehensible.

Also, for the code that uses some popular documented standards (including mentioned Javadoc, phpDocumentor and JSDoc), you can use automated documentation generators. For example, such generator tool can create a bunch of nice-looking HTML files that describe your API, contain methods index and cross-links, acceptable argument values, etc. These HTML files can be hosted on a web server and used by partners using your API or the programmers developing it. Each time some docblocks are changed, these files are re-generated, providing actual product information.

…And finally, what's about StyleDoc?

Advantages provided by StyleDoc

Programmers that use Javadoc, phpDocumentor or JSDoc get their code described in a simple, comprehensible way. They also possess automated tools to generate human-readable documentation.

StyleDoc provides similar experience for frontend coders that do CSS, LESS, SASS/SCSS or Stylus code.

• A short and neat way to describe your CSS selectors, theirs usage variations and examples
• Not implemented A similar way to describe your mixins
• A documentor tool available for both server-side (NodeJS) and client-side (browser) usage
• And this all comes in familiar Javadoc-flavoured syntax

The tool generates a live demo based on selector variations and examples markup in your docblocks, and applying real styles from your stylesheet.

Such kind of demo is useful for your mate developers, designers or managers: they all get an ability to see what you already have in project styles (and what you have not), how that looks, which variations have, and how can be used.

For example the tool can create a live demo just like this one, basing on the following docblocks in your code .

/**
 * Buttons
 * @base button Normal button
 * @modifier .bright Bright variation of button
 * @modifier .large Large-sized button
 * @modifier .large.bright Large-sized bright button
 * @state :disabled Unpressable button
 * @example <button>Button text</button>
 */
...your buttons styles follow...

/**
 * Checkboxes
 * Using label::before to apply custom box style
 * @base input[type="checkbox"] Normal checkbox
 * @modifier .large Large-sized checkbox
 * @state :checked Pre-checked checkbox
 * @state :disabled Unchangeble checkbox
 * @state :disabled:checked Unchangeble pre-checked checkbox
 * @example
 *     <input type="checkbox" id="unique_id">
 *     <label for="unique_id">Checkbox label</label>
 */
...your checkboxes styles follow...

Besides normal /** docblocks, StyleDoc also supports /*! docblock format, which can be used in Stylus CSS preprocessor.