This document outlines how documentation is handled in phoenix.

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.

There are two main components to the docs folder:

1. The contents of the docs folder are automatically pushed into gitHub wiki as a sub folder 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.

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

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

// @INCLUDE_IN_API_DOCS 

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 createJSDocs 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.

This document outlines how documentation is handled in phoenix.

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.

There are two main components to the docs folder:

1. The contents of the docs folder are automatically pushed into gitHub wiki as a sub folder 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.

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

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

// @INCLUDE_IN_API_DOCS 

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 createJSDocs 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.

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

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

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");

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

Use this to put constants or type definitions

/**
 * The max audit entries, default is 3000
 * @const {number}
 */
const MAX_AUDIT_ENTRIES = 3000;

Will Result in the following Markdown

MAX_AUDIT_ENTRIES

The max audit entries, default is 3000

Type: number

Use this to doccment Objects

/**
 * 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

/**
 * 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

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);

Additional tags can be found at the JSDocs docs at JSDocs