Skip to content

PROCEED JSDoc Documentation

Jump to bottom
iaktern edited this page Mar 11, 2023 · 2 revisions

The PROCEED JSDoc documentation is mainly for getting a good overview/understanding of the implemented functionalities for the developer.

Although we mainly use JSDoc to document the code inside the source files, JSDoc can create a HTML-Documentation out of the source files. If you want to see the JSDoc output or want to test if the written JSDoc code is correct, execute this command locally:

yarn jsdoc

Afterwards the generated HTML files are in ./jsdoc/output_html. You can open the index.html to see the JSDoc documentation.

For configurations of the JSDoc output, see the README inside the jsdoc folder.

This wiki page shows how to add the correct JSDoc keywords to get a good documentation.

Describing classes and functions

Use the usual JSDoc tags to describe functions and classes

A function/class should usually at least have a JSDoc description (what+why), parameter list with types, and return values.

/**
 * Return the engines running a process with the given id
 * 
 * @param {string} processID - the id of the process the engine is executing
 * @returns {String[]} all engines running instances of the process with the given id
 */
 getEnginesWithProcessID(processID) { ...}

Vue Component Files

Vue files (*.vue) can also be documented. Inside methods: you can normally use JSDoc comments before every function.

  ...
  methods: {
    /**
     * Deploys the given process
     *
     * @param {string} processToDeploy - process to be deployed as xml
     */
    deployProcess(processToDeploy) {
      ...

For data, props, computed, events there are special tags that should be used before export default { ...: @vue-prop, @vue-data, @vue-computed, @vue-event

...
<script>
  /**
   * @vue-prop {Number} initialCounter - Initial counter's value
   * @vue-prop {Number} [step=1] - Step
   * @vue-data {Number} counter - Current counter's value
   * @vue-computed {String} message
   * @vue-event {Number} increment - Emit counter's value after increment
   * @vue-event {Number} decrement - Emit counter's value after decrement
   */
  export default {
    props: { ...

For data, instead of using @vue-data on the top, you can alternatively describe it directly in data(). The HTML output is not so nice, but it is actually preferred, because it documents the Members directly where they are declared in the code:

 * don't do this:
 * @vue-data {number} currentTab
 *
 */
export default {
  data() {
    return {
      // Preferred:
      /**
       * Indicates the current tab
       * @type {number}
       */
      currentTab: 0,
      ...

Creating a module or a class

A module or a class creates a new documentation page visible in the generated JSDoc output. E.g. in the following picture @proceed/machine, rotation, writer, ... are modules (lowercased) and ConfigHandler, Logging, MachineManager, ... are classes (capitalized)

image

A module is used if the JS file only consists of functions (no class):

/**
 * Description of the modules functions
 *
 * @module @proceed/machine
 */

And a class is used, if the JS file contains a class or object, which will be exported and contains further methods:

/**
 * Class for initializing and getting a logger
 *
 * @class
 */
function Logging(){
  ...

If you use the ES6 class keyword, the JSDoc @class tag is actually not necessary, but recommended. If its an object, this tag is needed.

/**
 * Object that manages the execution of **all** BPMN processes.
 * It is a Singleton.
 *
 * @class 
 * @hideconstructor
 */
const management = {

@hideconstructor is often needed because it indicates a Singleton and that it's not possible to create a new object out of the class. Therefore it's also preferred to use the object notation in your code, because it better indicates a Singleton. If you use ES6 class, then make sure to use @hideconstructor directly over the constructor.

JSDoc requires a textual description before any JSDoc @-tag is used. Alternatively you can use @description at every point.

Please don't mix functions (@module) and classes (@class) in one JS file.
It's possible, but it's not beautiful.

Visually Nesting

The modules and classes can be nested to get a good looking tree structure in the JSDoc output, as seen in the above picture.

Therefore use @memberof. If its under a module, prepend the module name with "module:"

/**
 * Class for initializing and getting a logger
 *
 * @memberof module:@proceed/machine
 * @class
 * @hideconstructor
 */
class Logging {

Under a class:

/**
 * @memberof Logging
 * @class
 */
class Logger {

Multi-Nesting

You can have multiple layers of nesting. Separate them by a "."

If the JS class should be under a class, which is already under a module:

/**
 * @memberof module:@proceed/machine.Logging
 * @class
 */
class Logger {

If the JS file (@module) should be under a module, which is already under a module:

/**
* @module logLevelUtils
* @memberof module:@proceed/machine.Logging.module:rotation
*/

Vue Files

Write the module definition and nesting infos before export default {

import CapabilityInfo from '@/components/capabilities/CapabilityInfo.vue';

/**
 * @module views
 */
/**
 * @memberof module:views
 * @module Vue:Capabilities
 * 
 * @vue-computed machinelessCapabilities
 * @vue-computed capabilitiesWithMachine
 */
export default { ...

Not Recommended

If in a JS file there are functions and classes (the file contains both: @module and @class), the module contains the classes. So if you want to link to the class (e.g. for nesting it), you have to use a "~":

/**
* @memberof module:@proceed/machine.module:logging~Logging
*/

Here a module logging contains a class Logging and is itself under a module @proceed/machine

This is the Dev Wiki

Clone this wiki locally