sgilroy / jsdoc-plugin-mongoose Goto Github PK

This repository contains a JSDoc plugin for use with Mongoose.

This plugin will automatically generate JSDoc documentation from Mongoose schemas for corresponding models, including data types of fields and contextual descriptions.

Given a Mongoose schema, defined as below, appropriate documentation will be generated.

const mongoose = require('mongoose');

/**
 * Blog post
 */
const BlogSchema = new mongoose.Schema({
  /**
   * Title of the blog post which will be used as the header.
   */
  title: String,
  /**
   * Array of comments, each with a body and date.
   */
  comments: [{body: String, date: Date}],
  date: {type: Date, default: Date.now},
  hidden: Boolean
});

/**
 * Adds a comment to a blog post.
 * @param {String} body The body of the comment
 */
BlogSchema.methods.addComment = function(body) {};

/**
 * Finds blog posts from today.
 */
BlogSchema.statics.findCurrentBlogPosts = function() {};

module.exports = mongoose.model('Blog', BlogSchema);

The resulting documentation will include top-level schema paths as members of the inferred class:

Class: Blog

Blog post

Extends

mongoose.Model

Members

comments :Array.<Object>

Array of comments, each with a body and date.

date :Date

hidden :Boolean

title :String

Title of the blog post which will be used as the header.

Methods

findCurrentBlogPosts()

Finds blog posts from today.

addComment(body)

Adds a comment to a blog post.

To use this plugin, include it as one of the plugins in your JSDoc configuration. Uses of new mongoose.Schema in your code will be detected and result in documentation being generated for the corresponding model and its members (see example above).

1. Install this plugin globally or as a dev dependency, or copy it to the plugins folder located in the JSDoc installation folder.

   $ git clone https://github.com/sgilroy/jsdoc-plugin-mongoose

2. Include the plugin in your jsdoc-conf.js file. If the plugin is not installed in the plugins folder, specify a relative or absolute path to the plugin.

   module.exports = {
     plugins: ['plugins/jsdoc-plugin-mongoose']
   };

3. Run JSDoc from the command line and pass the configuration file to it.

   $ jsdoc -c jsdoc-conf.js

The plugin will generally infer that properties are part of a mongoose schema and thus associate them with the appropriate class automatically if the property is defined directly as a child of a schema declaration. For example:

const BlogSchema = new mongoose.Schema({
  /**
   * Title of the blog post which will be used as the header.
   */
  title: String
});

Here the title is inferred to be a member of the Blog class by being part of the BlogSchema declaration. However, you may want to define some or all of the schema properties separately from creating the schema. In such cases, the @schemaof tag should be used to tell the plugin to treat the properties as part of a mongoose schema definition. For example:

/**
 * @schemaof Blog
 */
const blogSchemaObject = {
  /**
   * Title of the blog post which will be used as the header.
   */
  title: String
};
const BlogSchema = new mongoose.Schema(blogSchemaObject);