Project: Grafana (Observability and Analysis / Observability)
File: code-comments.md

This document aims to give you some recommendation on how to add code comments to the exported code in the grafana packages. Each package has an overview explaining the overall responsibility and usage of the package. You can document this description with tag. Add this tag to the `<packageRoot>/src/index.ts` entry file to have one place for the package description. All `exported` apis from the package should have a release tag to indicate its stability. - early draft of api and will probably change. - close to being stable but might change. - ready for usage in production. - for internal use only. Add a tag to mark the stability of the whole exported `class/interface/function/type` etc. Please place the `release tag` at the bottom of the comment to make it consistent among files and easier to read. Do: ````typescript / Will help 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 ````typescript / Will help 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 {} } ```` Add the main stability of the API at the top according to . Then override the non-stable parts of the API with the proper . This should also be place at the bottom of the comment block. Do: ````typescript / Will help 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 ````typescript / Will help to create DataFrame objects and handle the heavy lifting of creating a complex object. * @example ```typescript const dataFrame =

``` / export class DataFrameFactory { / @public / create(): DataFrame {} / @beta / createMany(): DataFrame[] {} } ```` If you want to mark an API as deprecated to signal that this API will be removed in the future, then add the tag. If applicable add a reason why the API is deprecated directly after the `@deprecated tag`. If you want to specify the possible parameters that can be passed to an API, then add the 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: ```typescript / Will help 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 ```typescript / Will compare two numbers to see if they are equal to each others. * @param x - The first number @param y - The second number @public / export const isEqual = (x: number, y: number): boolean => { return x === y; }; ``` If you want to specify the return value from a function you can use the 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 function returns. Do: ```typescript / Will help 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 ```typescript / Will compare two numbers to see if they are equal to each others. * @returns true if values are equal @public / export const isEqual = (x: number, y: number): boolean => { return x === y; }; ```