README

We use the jsdoc tool to create API documentation.

What does the documentation consist of:

• Static documentation - here is a tutorial and description of classes
• Description of API methods - located in the API implementation files.
• Snapshots - here is the generated documentation for each version.
• index.html - this is the entry point for https://musescore.github.io
• Tools for generation - here you will find a documentation extractor for API methods, a documentation generator (jsdoc) and automation scripts.
• Generation and update process - see description below

Static documentation

location: docs/apidocs_static

This is where static documentation is stored in the jsdoc format.

• index.md - home page of documentation
• Tutorials - see jsdoc documentation about tutorials.

Description of API

Descriptions of API methods are located in .cpp,.h files where the implementation of the methods is located.
The description is in jsdoc format (see https://jsdoc.app), but the first line should indicate that this is APIDOC documentation.

Namesapces

Like api.log., api.interactive....

/** APIDOC
 * Write messages to log and console
 * @namespace log
 */
LogApi::LogApi(api::IApiEngine* e)
    : ApiObject(e)
{
}

There must be the @namespace tag with the namespace name

Classes (types)

/** APIDOC
 * Class representing a lyric.
 * @class Lyric
 * @hideconstructor
*/
class Lyric : public EngravingItem
{
    ...

There must be the @class tag with the class name
If the type cannot be created in js using the new operator,
then we need to add the @hideconstructor tag

Methods

/** APIDOC
 * Show information message
 * @method
 * @param {String} title Title
 * @param {String} text Message
 */
 void InteractiveApi::info(const QString& contentTitle, const QString& text)
{

There must be the @method tag

Properties

/** APIDOC @property {number} - count of lyrics */
int Score::lyricCount() const

There must be the @property tag, the description should be in one line

Enums

    /** APIDOC
     * Question buttons
     * @enum
     */
    enum Button {
        ...
    };    

There must be the @enum tag

When generating documentation, we first extract this documentation from the cpp files.

Snapshots

location: snapshots

To be able to view the documentation for each version, we generate snapshots of the documentation for each version and place them in the appropriate folder, for example: snapshots/4.5, snapshots/4.6

index.html

location: index.html - this is the entry point for https://musescore.github.io

After generating a snapshot for a new version, we need to add a link to it in this index.html, like others.

Tools for generation

location: tools/jsdoc

List of tools:

• template - template for jsdoc
• jsdoc_extractor.js - this is a documentation extractor from cpp files. It extracts documentation and stores it in temporary, fake js files so that jsdoc can process them.
• conf.json - file of configuration for jsdoc
• jsdoc_install.sh - script of jsdoc install
• jsdoc_run.sh - script for executing the generation process

This tool requires node.js and npm to be installed to work. To run scripts on Windows, use GitBash.

The generated documentation is placed in a temporary dir gen_apidoc.

Generation and update process

When developing a new version of an application, adding new APIs or changing current ones, or for those that don't have documentation, we need to write documentation, just like any other change in the repository.

After releasing a new version of the application, we need to generate a snapshot of the API documentation for it.

Process:

1. Install node.js and npm
2. Run bash ./tools/jsdoc/jsdoc_install.sh
3. Run bash ./tools/jsdoc/jsdoc_run.sh
4. Look the result, open it in browser index.html from ./tools/jsdoc/gen_apidoc/
5. Clone musescore.github.io
6. Copy dir ./tools/jsdoc/gen_apidoc/ to musescore.github.io/snapshots/x.x
7. Add a link to the new version in musescore.github.io/index.html