How to doc

Introduction

This is a quick guide for adding documentation using JSDoc

The documentation for the v4 branch is accessible from this url: http://cartodb.github.io/cartodb.js/

API

The command npm run docs generates the public API documentation in the docs\v4 directory. Only the comments tagged with @api will be included in the doc.

Internal

The command npm run docs:all generates the private documentation in the docs\v4-internal directory. All the comments in the code will be included in the doc.

Table of contents

• Global
  • Method
  • Constructor
  • Arguments
• Classes
  • Model

Global

Method

/** This is a description of the foo function.*/
function foo() {
}

API method

/** This is a description of the foo function.
  * @api
  */
function foo() {
}

Constructor

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

Arguments

/**
 * Represents a book.
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function book(title, author) {
}

Classes

Model

var MyModel = Backbone.Model.extend(
  /** @lends MyModel.prototype */
  {
    /**
     * This is the model description
     *
     * @augments Backbone.Model
     * @constructs
     */
    initialize: function () {
    },

    /**
    * My test method
    * @memberof MyModel
    * @method test
    * @param {object} args description
    * @return {number}
    */
    test: function (args) {
    }
  }
);

API model

var MyModel = Backbone.Model.extend(
  /** @lends MyModel.prototype */
  {
    /**
     * This is the model description
     *
     * @augments Backbone.Model
     * @constructs
     * @api
     */
    initialize: function () {
    },

    /**
    * My test method
    * @memberof MyModel
    * @method test
    * @param {object} args description
    * @return {number}
    * @api
    */
    test: function (args) {
    }
  }
);

Misc

Punctuation marks

• Dont use` final period in @param @returns
• use final period in global descriptions and long paragraphs.