02 Writing Docs

This document outlines how documentation is handled in Phoenix.

The docs folder

The docs folder in Phoenix repo is the main code/API/Extension docs folder for Phoenix. Most of the Phoenix GitHub Wiki is autogenerated from the contents of this folder.

Docs Folder Structure

There are two main components to the docs folder:

1. The contents of the docs folder are automatically pushed into gitHub wiki as a subfolder generatedDocs. Make changes to Markdown files in this folder to update wiki entries.
2. The docs in the docs/generatedApiDocs are autoGenerated API docs from source. These markdown docs should never be manually edited as their contents will be reset when autogenerated and all manually made changes will be lost.

How To Write API docs

This section covers how API docs are auto generated and how you can update API docs.

To Include any .js file containing JSDoc in Phoenix API docs, have this comment in any part of the file:

// @INCLUDE_IN_API_DOCS 

Writing JSDoc in source

Let us consider this example source file src/utils/Metrics.js. The file is created with JSDoc compliant source code comments. Make changes to the source code comments as required.

When you run npm run createJSDoc or npm run build the corresponding docs for the js file are automatically generated at docs/generatedApiDocs/utils/Metrics-API.md.

The generated docs should be pushed to Phoenix repo if there are any doc changes. Once the changes are pushed, the build system will update the docs in all wikis/ doc sites automatically.

JSDoc Examples

This section outlines the various tags available in JSDoc to style docs with examples.

note: All comment blocks with the @private tag will be ignored and won't appear in the docs.

1. Declaring a Module with @module tag

Use this to declare top level JS modules

/**
 * The Metrics API can be used to send analytics data to track feature usage in accordance with users privacy settings.
 *
 *`Status: Internal - Not to be used by third party extensions.`
 *
 * ### Import
 * ```
* // usage within core:
* const Metrics = require("utils/Metrics");
*
* // usage within default extensions:
* const Metrics = brackets.getModule("utils/Metrics");
* ```
*
* @module utils/Metrics
  */

Will Result in the following Markdown

utils/Metrics

The Metrics API can be used to send analytics data to track feature usage in accordance with users privacy settings. Status: Internal - Not to be used by third party extensions.

Import

// usage within core:
const Metrics = require("utils/Metrics");
// usage within default extensions:
const Metrics = brackets.getModule("utils/Metrics");

2. Putting custom section in Markdown using @name tag

Use this to put custom markdown anywhere in the doc file.

/**
 * This section outlines the properties and methods available in this module
 * @name API
 */

Will Result in the following Markdown

API

This section outlines the properties and methods available in this module

3. types/constants using @type or const

Use this to put constants or type definitions

/**
 * The maximum number of audit entries; default is 3000.
 * @const {number}
 */
const MAX_AUDIT_ENTRIES = 3000;

Will Result in the following Markdown

MAX_AUDIT_ENTRIES

The maximum number of audit entries; default is 3000.

Type: [number]

4. Objects using @typedef and @type

Use this to doccment Objects

Method 1

/**
 * The Type of events that can be specified as an `eventType` in the API calls.
 *
 * ### Properties
 * `PLATFORM`, `PROJECT`, `THEMES`
 *
 * @typedef EVENT_TYPE
 * @type {Object}
 */
const EVENT_TYPE = {
    PLATFORM: "platform",
    PROJECT: "project",
    THEMES: "themes"
};

Will Result in the following Markdown

EVENT_TYPE

The Type of events that can be specified as an eventType in the API calls.

Properties

PLATFORM, PROJECT, THEMES

Type: [Object]

Method 2

/**
 * The Type of events that can be specified as an `eventType` in the API calls.
 *
 * @typedef EVENT_TYPE
 * @type {Object}
 * @property {string} PLATFORM
 * @property {string} PROJECT
 * @property {string} THEMES
 */
const EVENT_TYPE = {
    PLATFORM: "platform",
    PROJECT: "project",
    THEMES: "themes"
};

Will Result in the following Markdown

EVENT_TYPE

The Type of events that can be specified as an eventType in the API calls.

Type: [Object]

Properties

• PLATFORM [string]
• PROJECT [string]
• THEMES [string]

5. Function docs with @function or method

Use this to document a function and its arguments/returns/exceptions.

Note that the EVENT_TYPE is autodetected and hyperlinked by the framework

/**
 * log a numeric count >=0
 *
 * @example <caption>To log that user clicked searchButton 5 times:</caption>
 * Metrics.countEvent(Metrics.EVENT_TYPE.UI, "searchButton", "click", 5);
 *
 * @param {EVENT_TYPE|string} eventType The kind of Event Type that needs to be logged- should be a js var compatible string.
 * Some standard event types are available as `EVENT_TYPE`.
 * @param {number} count >=0
 * @type {function}
 */
function countEvent(eventType, count) {}

Will Result in the following Markdown:

countEvent

log a numeric count >=0 Type: [function][2]

Parameters

• eventType ([EVENT_TYPE] | [string]) The kind of Event Type that needs to be logged- should be a js var compatible string. Some standard event types are available as EVENT_TYPE.
• count [number] > =0

Examples

To log that user clicked searchButton 5 times:

Metrics.countEvent(Metrics.EVENT_TYPE.UI, 5);

6. More tags

Additional tags can be found at the JSDoc docs at JSDoc