Skip to content

Guide

Jump to bottom Edit New page
nene edited this page Mar 21, 2012 · 60 revisions

Writing documentation is hard. Writing good documentation is even harder. And most developers are under ever-lasting pressure to concentrate on everything besides the documentation. There is never enough time for writing the docs.

And that's why JSDuck aims to make documentation as painless as possible.

First off JSDuck chooses Markdown to ease the structuring of text:

/**
 * Returns description of the time of the day.
 *
 * Different heuristics are used to come up with the **most** appropriate
 * wording for the current user.
 *
 * @return {String} Possible return values are:
 *
 * - midday
 * - late night
 * - early morning
 * - just before lunch
 * - tea time
 */
getDayTime: function() {

You can also use HTML, because Markdown allows embedding of HTML, which will come in handy if you have a lot of legacy documentation written for ext-doc.

Second, JSDuck tries to infer as much information from code as possible. For this it looks at the code that immediately follows the doc-comment. To see this in action, we have to get into the details...

Classes

Documenting an Ext JS 4 class will be a breeze if you are using the standard Ext.define syntax:

/**
 * A duck, not just a stupid bird.
 */
Ext.define("Duck", {
    extend: "Bird",
    mixins: {
        observe: 'Ext.util.Observable',
        fly: 'Fliable'
    },
    singleton: true,

JSDuck will automatically recognize that this is a doc-comment for class Duck and will auto-detect several tags from the config object: @extends, @mixins and @singleton.

But JavaScript is a dynamic language and there are bazillion ways to define a class. JSDuck will only auto-detect all these properties when you strictly follow the above form. But don't lose hope, you can always use @tags to say things explicitly:

    /**
     * @class Duck
     * A duck, not just a stupid bird.
     * @extends Bird
     * @mixins Ext.util.Observable
     * @mixins Fliable
     * @singleton
     */
    var x = {};

JSDuck also supports Ext.extend syntax from Ext JS 3, automatically detecting the name of the class itself and its parent:

/**
 * A duck, not just a stupid bird.
 */
Duck = Ext.extend(Bird, {
    ...
});

See @class documentation for details.

Members

All doc-comments following a class doc-comment will be assumed to be members of that class. There are four types of members: configs, properties, methods, events.

Only methods are auto-detected. Everything not looking like a method will be assumed to be a property. So be sure to always use @event and @cfg for documenting events and configs.

Methods

Here's an example of typical method documentation with [@param][] and [@return][] tags:

/**
 * Returns a unique ID for use in HTML id attribute.
 * @param {String/Number} nr A name or number of the ID.
 * @param {String} [prefix="id-"] The prefix for the ID.
 * @return {String} the new ID
 */
createId: function(nr, prefix){
},

You can see the types of parameters and return value (inside curly braces) and the syntax for optional parameter (enclosed in square brackets) and its default value.

Constructors are documented just like normal methods:

/**
 * Creates new Duck from proper duck egg.
 * @param {DuckEgg} egg  Egg with DNA configuration for new duck.
 */
constructor: function(egg) {

See @method for details.

Events

Events are a lot like methods, except that they don't have return values.

/**
 * @event
 * Triggered after component gets hidden.
 * @param {Ext.Component}
 */
"hide",

@event tag can be followed by event name, but in the above case it is auto-detected.

See @event for details.

Configs

Configs are a lot like method parameters. They can have default values and sub-properties.

/**
 * @cfg {Object} size Size of the item.
 * @cfg {Number} [size.width=0]
 * @cfg {Number} [size.height=0]
 */
size: {width: 0, height: 0},

For configs with simple literal values one can take advantage of auto-detection:

/**
 * @cfg
 * CSS class names to apply for root element.
 */
cls: ["x-component", "x-item"],

The above will be auto detected as config option cls of type String[] with default value ["x-component", "x-item"].

See @cfg for details.

Properties

The syntax for @property is almost the same as for @cfg:

/**
 * @property {Boolean} [readOnly=false]
 * True when component is in read-only state.
 */

Like with configs, you can take advantage of auto-detection. And with properties you can leave off the @property tag entirely:

/**
 * True when component is in read-only state.
 */
readOnly: false,

See @property for details.

Type definitions

Throughout this guide you've seen type definitions like {Number}. These aren't just arbitrary strings enclosed in curly braces - there's a specific syntax for specifying types and JSDuck will check that you follow it. Here's a short overview of supported syntax:

  • {Ext.Element} - a single Ext.Element.
  • {String[]} - array of strings.
  • {String[][]} - 2D array of strings.
  • {Number/String/Boolean} - either number, string, or boolean.
  • {Boolean...} - variable number of boolean arguments.

In addition to this, JSDuck has full support for Google Closure Compiler Type Expressions. So you can even use complex type expressions like this:

  • {function((number|string), RegExp=): boolean}

JSDuck will also check that you don't reference any unknown types. For example if you specify {Foo} and you don't have class Foo included to you documentation, JSDuck will produce a warning. Warnings aren't thrown for JavaScript primitive types:

  • boolean
  • number
  • string
  • undefined
  • void

for built-in JavaScript types:

  • Object
  • String
  • Number
  • Boolean
  • RegExp
  • Function
  • Array
  • Arguments
  • Date
  • Error

and for few DOM types:

  • HTMLElement
  • XMLElement
  • NodeList
  • TextNode
  • CSSStyleSheet
  • CSSStyleRule
  • Event

To make JSDuck ignore some other type names use --external=Foo,Bar,...

To document a variable that can be of any type whatsoever, use the Mixed type. But try to keep its use to the minimum, always prefer the {Foo/Bar/Baz} syntax to list possible types.

Cross-references

Inside comments you can link to classes and class members using the {@link} tag:

{@link Class#member link text}

But JSDuck will also automatically create links to classes if it sees NameSpace.Class, SomeClass#method or #method.

For example:

Look at the {@link Duck} class.  There are methods like
Duck#fly and Duck#swim and even this
{@link Duck#walk particularly slow method}.

Now compare it to #move method of this class, that does
all the above.

This will produce something like this:

Look at the Duck class. There are methods like Duck.fly and Duck.swim end even this particularly slow method.

Now compare it to move method of this class, that does all of the above.

Sometimes the name is not enough to uniquely identify a class member. For example Ext.data.Store has a load method and load event. In such case, prepend cfg-, property-, method- or event- to the member name:

Listen to the {@link Ext.data.Store#event-load load event}

Or you might need to reference a static method when an instance method of the same name exists:

Use {@link Ext.form.field.Field#static-method-getName getName} to get class name.

For links to other websites, and things within the docs app itself like guides, use Markdown links:

See [Getting Started Guide](#!/guide/getting_started) or check
out [Sencha website][1] for more.

[1]: http://www.sencha.com/

For links to guides, videos and examples, check out also the @aside tag.

Images

You can include images inside the documentation using the {@img} tag:

{@img path/to/image.png alt text}

The paths should be relative to the directory specified by --images option (there can be more than one to list multiple search paths).

For ExtJS 4 you can simply refer to the doc-resources directory of downloaded release:

$ jsduck extjs-4.0.7/src --images=extjs-4.0.7/docs/doc-resources --output my-docs

All the linked images will then be copied over to output directory, while {@img} tags will become repleced with markup like:

<p><img src="doc-resources/path/to/image.png" alt="alt text"/></p>

For full control over the created markup you can use the --img command line option.

Videos

This feature should be considered experimental, but at the moment you can include videos from Vimeo with a simple line like that:

{@video vimeo 465123 Some description here...}

The number is Vimeo clip ID.

Add a custom footer
Add a custom sidebar
Clone this wiki locally