Home

Topdoc Comment Spec

Topdoc generates the documentation from comments in the css. Currently the spec we are using is based on kss, but it doesn't quite do what we need it to, and things could be more definite. So, let's fix it by adding more stuff!

This is a humble proposal.

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)

The first two are easy, the last one is tricky. We could be literal like this:

/* topdoc
  identifier example A
*/

or 

/* td
  identifier example B
*/

That seems dumb.

How about something simpler:

/* ---
  identifier example C
*/

I think that would work, but what about fun?

/* |`-
  identifier example D
*/

get it? it looks like a painter roller a little right? that might just be annoying more than useful.

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)
• corresponding markup example
• psuedo (needed?)

/* ---
  name: Button
  description: It's a button, not that complicated
  example:
    <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 */
}

What about?

• tags
  • We could tag individual components with stuff like, input, button, dark, desktop, etc
• flags
  • This could be something useful to the template - an example is overlay. It will probably need to be wrapped in an iframe, so maybe the template will need to be able to do something different for just this component.
• template data
  • This could take the place of flags, this would just be general data that would be passed through to the template. Maybe we could just let developers type in whatever they want, and it will parse it and pass it through as a json object.
• dependencies
  • a regex, or array of selectors, that can be used to find corresponding selectors and rulesets that affect the component.
  • The idea being that there could be some general css rulesets that are being used by several examples

Document Data

• name
  • The file name is given, since it is in the file, but this would be a display name, like Topcoat Dark Desktop.
• template
  • Maybe this file uses an alternate template file, instead of the default index.jade file.
• template data
  • same as above, but more general to the whole document.

Let's put all this stuff together.

###What would it look like?

Maybe something like this:

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

/* ---
  name: Button
  description: It's a button, not that complicated
  example:
    <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 */
}

/* ---
  name: Overlay
  description: Cover up all the ui, and show a modal to the user.
  iframe: true
  dependencies: topcoat-button, topcoat-button--cta
  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 */
}