Comparisons

Goals:

• Support flexible data, but defintely the following:
  • Name
  • display component
  • display code snippet - html, css blocks
  • url to bin example js
  • tags (ie. dark, desktop, mobile, etc.)
  • flags like whether the components needs to be in an iframe
• Node.js based (users shouldn't have to install new environments just to use our tools)
• Customizable template

Available Solutions:

##Styledocco

Features:

• Node based
• Follows kss style of documentation
• Psuedo class modifiers

Lacking:

• url to bin example js
• tags (ie. dark, desktop, mobile, etc.)
• flags like whether the components needs to be in an iframe
• Customization

##KSS

Features:

• Description
• Modifiers (states, etc.)
• Styleguide section - to link to a section in the style guide

Pros:

• Good following
• Well tested

Lacking:

• Node support
• Markup code is separate
• No support for custom data

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

Styleguide 2.1.3.
*/

##CSS Doc

Features:

• Extracts file-scope documentation for each CSS source file.
• Extracts documentation for rule sets (i.e. a set of selectors separated by commas with a declaration).
• Files can be separated into several sections.
• For rule set documentation, html code examples can be incorporated into the documentation.
• Generates selector, section and file index pages.

Lacking:

• Node support

##Kalei

Features:

• Custom data

Lacking:

• Command line tool
• Data structure - It is a little too flexible

#Related Solutions: These aren't specifically for css, but are good reference.

##Tomdoc

Pros:

• highly structured

Cons:

• no room for custom data
• really designed for ruby or similar object oriented code

# Public: Duplicate some text an arbitrary number of times.
#
# text  - The String to be duplicated.
# count - The Integer number of times to duplicate the text.
#
# Examples
#
#   multiplex('Tom', 4)
#   # => 'TomTomTomTom'
#
# Returns the duplicated String.
def multiplex(text, count)
  text * count
end

##ASDoc

Pros:

• Details
• Supports rich formatting
• Supports inheritance

Cons:

• For Actionscript :)

/**
* This is the typical format of a simple multiline comment
* for the myMethod() method.
*
* <p>This is the second paragraph of the main description
* of the <code>myMethod</code> method.
* Notice that you do not use the paragraph tag in the
* first paragraph of the description.</p>
* 
* @param param1 Describe param1 here.
* @param param2 Describe param2 here.
* 
* @return A value of <code>true</code> means this; 
* <code>false</code> means that.
*
* @see someOtherMethod
*/
public function myMethod(param1:String, param2:Number):Boolean {}