meteor-jsdoc

v1.0.4

Published

2 years ago

Automated JSDoc generation for Meteor projects with a Meteor server to output the docs.

Downloads

0High
0Medium
0Low

fabienb4

Meteor JSDoc

Automated JSDoc generation for Meteor projects

Meteor JSDoc is a command line tool which will help with generating documentation for your Meteor project. The result? A website like Meteor Docs.

If you are updating to 1.0.0, please check the CHANGELOG to do it properly.

meteor-jsdoc uses the development version of jsdoc to provide better support for new Javascript syntax. You might encounter errors due to jsdoc itself, not meteor-jsdoc. Be sure to check the known issues.

Table of Contents

Features

Based on the templates from Meteor own docs.
The generated docs are used as data by a Meteor app which displays a nicely formatted documentation for your app (like the Meteor Docs) at http://localhost:3333/ (configurable).
A configuration file allows project based configuration, avoiding problem of port already in use.
Markdown supported in @summary, @example & description in @param.
Support linking to files in Github or Bitbucket repositories.

Remember to check the CHANGELOG file when a new update with [BREAKING] or [TEMPLATE UPDATE] is released to make sure you are not missing new features!

Installation

Prerequisites:

node >= 5.5

On Windows, you must have git bash with Unix tools installed (find, xargs, grep are required).

Installation:

npm install -g meteor-jsdoc

Initializing a project

meteor create myproject
cd myproject
meteor-jsdoc init

This will create a config file in your Meteor project directory: jsdoc.json.

Config file

Show current configuration:

meteor-jsdoc conf

Default config:

{
  // Execute meteor-jsdoc in debug mode to track down errors.
  "debug": false,
  // node.js install path, default to: "`which node`" on Mac and Linux, "`where node`" on Windows
  "nodePath": "",
  // Project docs path
  "docsPath": "~/myproject-docs",
  // Project docs Meteor server port, default to: 3333
  "meteorPort": 3333,
  // Copy the Meteor docs server before building the docs (required for the first build)
  // Setting this to false after the first build allows you to customize the Meteor docs server
  // without seeing your changes overridden the next time you build the docs.
  "initMeteor": true,
  // Update Meteor without overwriting your changes to the docs templates.
  "updateMeteor": true,
  // Add a preamble to your project's docs that will appear at the top of the docs.
  "preamble": true,
  // Link to the project repository (used to construct the file path in the docs). Optional.
  "projectRepo": "https://github.com/username/myproject/tree/master",
  // Values to be used in the `<head>` for the docs.
  "docsConfig": {
    "title": "Meteor Project Docs",
    "metas": {
      "description": "Documentation for a meteor project."
    }
  }
}

<docsPath> has to be in a different folder than your project, or you will end up with a Meteor server inside a Meteor server.

"~" can be used to specify your home directory.

When using meteor-jsdoc build for the first time, it requires the initMeteor setting to be true, otherwise, only the data files will be copied, and you won't be able to start the docs server (there will be none).

<projectRepo> is used to construct the link to the repository of your project depending on the current function/variable.

With Github, be sure to include the branch in the link (/blob/master). Example: https://github.com/fabienb4/meteor-jsdoc/blob/master

With Bitbucket, be sure to include the hash of the current branch in the link. Example: https://bitbucket.org/FabienB4/meteor-jsdoc/src/ea598ce045211ee2f5db0ba50e594t96549acdad

<docsConfig> allows you to customize the <head> of your docs. Each meta gets added according to the key/value.

For the jsdoc-conf.json file see: Configuring JSDoc.

Preamble

If you want to add a preamble to your project's docs, you need to enable the option in jsdoc.json (enabled by default).

  "preamble": true

When building the docs, a file named preamble.md will be copied inside <docsPath>/client/templates.

The default preamble will NOT be copied if it is detected in your project's docs, so you can leave preamble to true in jsdoc.conf.

You can edit it to add any content you want, it will be displayed at the top of your project's docs. Do NOT change or remove the first and last lines inside the file.

Both Markdown and HTML syntaxes are supported in the file, but you should stick to Markdown to avoid any unwanted side-effects.

A table of content is generated automatically for you using the id="whatever" occurrences in the compiled preamble.md and displayed above the API links in the navbar. For this reason, you should use the markdown syntax for headers (# ... ######). This way each header will get a link in the navbar according to its type (h1 to h6).

If your preamble is no longer displayed in the docs, you can look at the app.log file in <docsPath> to see what went wrong.

Here is an example:

{{#template name="preamble"}}

# Meteor Project Docs
*****

## Header 1
This is paragraph one.

This is paragraph two.

## Header 2
### Header A
* Red
* Green
* Blue
### Header B
* Small
* Medium
* Large

{{/template}}

Adding documentation to your project

Some examples from the mongo package:

The @summary tag is required for the docs to be generated properly. Any method docs without it won't be processed by meteor-jsdoc.

/**
 * @summary Constructor for a Collection
 * @locus Anywhere
 * @instancename collection
 * @class
 * @param {String} name The name of the collection.  If null, creates an unmanaged (unsynchronized) local collection.
 * @param {Object} [options]
 * @param {Object} options.connection The server connection that will manage this collection. Uses the default connection if not specified.  Pass the return value of calling [`DDP.connect`](#ddp_connect) to specify a different server. Pass `null` to specify no connection. Unmanaged (`name` is null) collections cannot specify a connection.
 * @param {String} options.idGeneration The method of generating the `_id` fields of new documents in this collection.  Possible values:
 - **`'STRING'`**: random strings
 - **`'MONGO'`**:  random [`Mongo.ObjectID`](#mongo_object_id) values
The default id generation technique is `'STRING'`.
 * @param {Function} options.transform An optional transformation function. Documents will be passed through this function before being returned from `fetch` or `findOne`, and before being passed to callbacks of `observe`, `map`, `forEach`, `allow`, and `deny`. Transforms are *not* applied for the callbacks of `observeChanges` or to cursors returned from publish functions.
 */
Mongo.Collection = function(name, options) {
  /** ... **/
};

/**
 * @summary Find the documents in a collection that match the selector.
 * @locus Anywhere
 * @method find
 * @memberOf Mongo.Collection
 * @instance
 * @param {MongoSelector} [selector] A query describing the documents to find
 * @param {Object} [options]
 * @param {MongoSortSpecifier} options.sort Sort order (default: natural order)
 * @param {Number} options.skip Number of results to skip at the beginning
 * @param {Number} options.limit Maximum number of results to return
 * @param {MongoFieldSpecifier} options.fields Dictionary of fields to return or exclude.
 * @param {Boolean} options.reactive (Client only) Default `true`; pass `false` to disable reactivity
 * @param {Function} options.transform Overrides `transform` on the  [`Collection`](#collections) for this cursor.  Pass `null` to disable transformation.
 * @returns {Mongo.Cursor}
 */
find: function(/* selector, options */) {
  /** ... **/
}

Building the docs

meteor-jsdoc build

This will copy a basic Meteor server (v1.2.1) to the <docsPath> directory. And then build the documentation for your project in <docsPath>/client/data.

Starting the Meteor server

From your project folder you have two options:

First:

meteor-jsdoc start

This will automatically start the Meteor server in <docsPath> in the background. The default address is: http://localhost:3333/. The <meteorPort> option in jsdoc.json allows you to change the port.

Second:

cd <docsPath>
meteor

This will start Meteor as usual with the possibility to ctrl+c when you want to stop it.

First method doesn't currently work on Windows.

Stopping the Meteor server

If you started the Meteor server for the docs using meteor-jsdoc start, and want to stop it, the following command (to run from your project folder) is available:

meteor-jsdoc stop

This will stop the Meteor server associated with <docsPath> and <meteorPort>.

Custom jsdoc tags.

@isHelper true

  /**
   * @global
   * @name  currentUser
   * @isHelper true
   * @summary Calls [Meteor.user()](#meteor_user). Use `{{#if currentUser}}` to check whether the user is logged in.
   */
  Package.blaze.Blaze.Template.registerHelper('currentUser', function () {
    return Meteor.user();
  });

@isTemplate true

/**
 * @isTemplate true
 * @memberOf Template
 * @function dynamic
 * @summary Choose a template to include dynamically, by name.
 * @locus Templates
 * @param {String} template The name of the template to include.
 * @param {Object} [data] Optional. The data context in which to include the
 * template.
 */

@isMethod true

Meteor.methods({
  /**
   * @summary Meteor.methods wrapper for [Users.setRole](#Users-setRole).
   * @isMethod true
   * @locus Anywhere
   * @param  {String} role The role to set.
   */
  'Users.setRole'(role) {
    if (this.userId) {
      Users.setRole(this.userId, role);
    }
  }
});

@before & @after
These two custom tags are displayed before and after the documentation of a function/variable. You can add them if you want to specify something regarding it but don't want to put everything in the @summary (See example). Markdown is supported.

Updating

To update meteor-jsdoc to the latest version, just type:

npm update meteor-jsdoc -g

You should try and keep meteor-jsdoc up to date in order to keep up with the latest Meteor changes.