Home

Topdoc Comment Spec

Topdoc generates the documentation from comments in the css.

Recognition / Validation

Not all comments will be Topdoc comments, but Topdoc should be able to figure out what is useful and what should be ignored.

so - some rules, Topdoc comments should be:

• block comments
• standardize on indents (2 spaces, done)
• whitelist (assume nothing is a topdoc comment, unless it specifically identifies itself as a topdoc comments)

/* topdoc
  identifier example A
*/

Data

What is needed in to make awesome documentation? We need something for each individual component, and we could have a document header.

##Component Data

• name
• description (optional)
• modifiers
• examples
  • Usage guides to be included in. for Topcoat desktop & mobile By default examples would show up in both.

/* topdoc
  name: Button
  description: It's a button, not that complicated
  examples:
    desktop:
     <button class="topcoat-button">Button</button>
     <button class="topcoat-button is-active">Button</button>
     <button class="topcoat-button is-disabled">Button</button>

    mobile:
     <a class="topcoat-button">Button</a>
     <a class="topcoat-button is-active">Button</a>
     <a class="topcoat-button is-disabled">Button</a>
*/
.topcoat-button,
.topcoat-button--quiet,
.topcoat-button--large,
.topcoat-button--large--quiet,
.topcoat-button--cta,
.topcoat-button--large--cta {
    /* blah blah blah */
}

Misc. Data

Any other property is valid and will parsed by topdoc for use with your template. for instance:

/* topdoc
  name: Button
  description: It's a button, not that complicated
  examples:
    desktop:
     <button class="topcoat-button">Button</button>
     <button class="topcoat-button is-active">Button</button>
     <button class="topcoat-button is-disabled">Button</button>

    mobile:
     <a class="topcoat-button">Button</a>
     <a class="topcoat-button is-active">Button</a>
     <a class="topcoat-button is-disabled">Button</a>

   custom:
     responsive, theme
   data:
     etc.
*/

Let's put all this stuff together.

###What would it look like?

/*
Copyright 2012 Adobe Systems Inc.;
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

/* topdoc
  name: Button
  description: It's a button, not that complicated
  examples:
    desktop:
     <button class="topcoat-button">Button</button>
     <button class="topcoat-button is-active">Button</button>
     <button class="topcoat-button is-disabled">Button</button>

    mobile:
     <a class="topcoat-button">Button</a>
     <a class="topcoat-button is-active">Button</a>
     <a class="topcoat-button is-disabled">Button</a>
*/
.topcoat-button,
.topcoat-button--quiet,
.topcoat-button--large,
.topcoat-button--large--quiet,
.topcoat-button--cta,
.topcoat-button--large--cta {
    /* blah blah blah */
}

/* topdoc
  name: Overlay
  description: Cover up all the ui, and show a modal to the user.
  example:
    <div class="topcoat-overlay-bg"></div>
    <aside class="topcoat-overlay">
      <h1>Are eagles nice ?</h1>
      <div class="topcoat-overlay-buttons">
        <button role="button" class="topcoat-button">No</button>
        <button role="button" class="topcoat-button--cta">Yes</button>
    </div>
    </aside>
*/
.topcoat-overlay {
  /* blah blah blah */
}