Skip to main content

Documentation

When writing TypeScript code in Figuro, it is important to document your code to make it easier for other developers to understand and use your code. In this document, we will outline a standard format for documenting your TypeScript code using comments. The format includes documenting the purpose of each function, the parameters it accepts, and the value it returns. Additionally, you should document the purpose of each class, the properties it contains, and the methods it exposes.

However, it is important to note that the standard format may not be sufficient for more complex projects. In such cases, you may need to add additional comments to clarify the purpose of your code. You may also need to add comments to explain the rationale behind certain design decisions or to document any edge cases that may not be immediately obvious.

Basic Format​

Here is a basic format for documenting your Typescript code using comments:

/**
 * Brief description of the code element.
 *
 * @name Name of the code element.
 * @description Full description of the code element.
 *
 * @param {paramType} parameterName Description of the parameter.
 * @returns {returnType} Description of the return value.
 *
 * @example Example usage of the code element.
 *
 * @version Version number of the code element.
 * @author github username and email of the author.
 * @copyright Figuro Colombia Ltda.
 *
 * @todo Description of any work that still needs to be done.
 */

Comment Elements​

Let's go through each of the elements in the comment format:

Brief Description​

The brief description should provide a summary of the code element's purpose. It should be a short, one-line description that accurately describes the code element.

/**
 * @name useLocalStorage
 * @description Hook to use local storage, returns a function to get, set and remove the variable from local storage.
 */

Parameters​

If your code element takes any parameters, you should document them in your comment using @param. Plase note that you should also include the type of the parameter.

/**
 * @param {type} name the name of the variable in local storage.
 */

Return Value​

If your code element returns a value, you should document it using @returns. Again, you should also include the type of the return value.


```javascript
/**
 * @returns {type} [getLocalStorage, setLocalStorage, removeLocalStorage]
 */

Examples​

You can provide examples of how to use your code element using @example.

/**
 * @example const [getLocalStorage, setLocalStorage, removeLocalStorage] = useLocalStorage('name');
 */

Version and Author​

You should also include the version number and the author of the code element. Whenever applicable, you should also include the copyright information.

/**
 * @version 1.0.0
 * @author github username and email of the author. <email@figuro.la>
 * @copyright Figuro Colombia Ltda.
 */

To-Do​

Lastly, you can use @todo to document any work that still needs to be done.

/**
 * @todo Add additional functionality to this element.
 */
tip

Documenting your TypeScript code using comments is an essential part of writing clean, maintainable code in Figuro. By following this guideline, you can ensure that your code is well-documented and easy to understand.

Resources​

Here are some additional resources you can use to learn more about documentation in TypeScript:

  • TypeScript Handbook: Documentation Comments - This section of the TypeScript Handbook provides a detailed explanation of how to write documentation comments for TypeScript.
  • Typedoc - Typedoc is a tool that generates API documentation from TypeScript source code. It supports a variety of formats, including HTML and Markdown.
  • JSDoc - JSDoc is a popular syntax for documenting JavaScript and TypeScript code. It is supported by many editors and tools, and can be used to generate API documentation.