grafana/contribute/style-guides/code-comments.md

Guidelines for code comments in Grafana packages

This guide provides recommendations for adding code comments in grafana-\* packages.

Add package description

Each package has an overview explaining the overall responsibility and usage of the package.

Use the @packageDocumentation tag to document the package.

Add the @packageDocumentation tag to the <packageRoot>/src/index.ts entry file to have one place for the package description.

Set stability of an API

Add a release tag to all exported APIs from the package to indicate its stability.

• @alpha - denotes an early draft of API that will probably change.
• @beta - denotes that the API is close to being stable but might change.
• @public - denotes that the API is ready for usage in production.
• @internal - denotes that the API is for internal use only.

Indicate main stability of APIs

To indicate the main stability of APIs:

• Add a tag to mark the stability of the whole exported class/interface/function/type, and other interfaces.
• Place the release tag at the bottom of the comment to make it consistent among files and easier to read.

Do:

/**
 * Helps to create DataFrame objects and handle
 * the heavy lifting of creating a complex object.
 *
 * @example
 * ```typescript
 * const dataFrame = factory.create();
 * ```
 *
 * @public
 **/
export class DataFrameFactory {
  create(): DataFrame {}
}

Don't:

/**
 * Helps to create DataFrame objects and handle
 * the heavy lifting of creating a complex object.
 *
 * @public
 * @example
 * ```typescript
 * const dataFrame = factory.create();
 * ```
 **/
export class DataFrameFactory {
  create(): DataFrame {}
}

Indicate partial stability of APIs

To indicate the partial stability of APIs:

1. Add the main stability of the API at the top according to Main stability of API.
2. Override the non-stable parts of the API with the proper release tag. This tag should also be placed at the bottom of the comment block.

Do:

/**
 * Helps to create DataFrame objects and handle
 * the heavy lifting of creating a complex object.
 *
 * @example
 * ```typescript
 * const dataFrame = factory.create();
 * ```
 *
 * @public
 **/
export class DataFrameFactory {
  create(): DataFrame {}

  /**
   * @beta
   **/
  createMany(): DataFrames[] {}
}

Don't:

/**
 * Helps to create DataFrame objects and handle
 * the heavy lifting of creating a complex object.
 *
 * @example
 * ```typescript
 * const dataFrame = factory.create();
 * ```
 **/
export class DataFrameFactory {
  /**
   * @public
   **/
  create(): DataFrame {}

  /**
   * @beta
   **/
  createMany(): DataFrame[] {}
}

Deprecate an API

If you want to mark an API as deprecated to signal that this API will be removed in the future, then add the @deprecated tag.

If applicable, add a reason why the API is deprecated directly after the @deprecated tag.

Specify parameters

If you want to specify the possible parameters that can be passed to an API, then add the @param tag.

This attribute can be skipped if the type provided by typescript and the function comment or the function name is enough to explain what the parameters are.

Do:

/**
 * Helps to create a resource resolver depending
 * on the current execution context.
 *
 * @param context - The current execution context.
 * @returns FileResolver if executed on the server otherwise a HttpResolver.
 * @public
 **/
export const factory = (context: Context): IResolver => {
  if (context.isServer) {
    return new FileResolver();
  }
  return new HttpResolver();
};

Don't

/**
 * Compares two numbers to see if they are equal to each other.
 *
 * @param x - The first number
 * @param y - The second number
 * @public
 **/
export const isEqual = (x: number, y: number): boolean => {
  return x === y;
};

Set return values

To specify the return value from a function, you can use the @returns tag.

You can skip this attribute if the type provided by typescript and the function comment or the function name is enough to explain what the function returns.

Do:

/**
 * Helps to create a resource resolver depending
 * on the current execution context.
 *
 * @param context - The current execution context.
 * @returns FileResolver if executed on the server otherwise a HttpResolver.
 * @public
 **/
export const factory = (context: Context): IResolver => {
  if (context.isServer) {
    return new FileResolver();
  }
  return new HttpResolver();
};

Don't:

/**
 * Compares two numbers to see if they are equal to each other.
 *
 * @returns true if values are equal
 * @public
 **/
export const isEqual = (x: number, y: number): boolean => {
  return x === y;
};