Typescript: What is TSDoc?

The way to write the better comments

Photo by Monti Timpanogus on Unsplash

Writing good comments is pretty important when co-working with other developers in an organization. Although the best practice is not to leave any comments in the first place because the code is clear and easy enough to catch its functionality. But, sometimes, well-commented code can save plenty of time for the developers who read it and it leads to boosting their productivity. As a result, it makes code maintenance much easier.

So how can we document a comment well as a frontend developer? TSDoc might help you! I strongly recommend using this awesome guy. you might have heard about JsDoc which is a markup language used to annotate JavaScript source code files. TSDoc is based on JSDoc so it supports typescript extension as well as javascript.

What is TSDoc?

TSDoc is a proposal to standardize the doc comments used in TypeScript code, so that different tools can extract content without getting confused by each other’s markup. — tsdoc.org

TSDoc Example

TSDoc is doc comments for typescript code. You can define metadata and API documents for the code. Typescript provides static typing. By using this feature, you can document the detail of the code easily.

Visual Studio Code supports TSDoc syntax. If you leave comments using the syntax of TsDoc, the tag is automatically highlighted.

Syntax of TSDoc

Syntax is very simple. That’s all.

• Comment should start with /**.
• Tag uses @(e.g. @returns).

Types of TSDoc Tags

You can use tags to categorize the type of comment. I prepare some examples of the tags.

@deprecated: Used for deprecated code(APIs) which is no longer supported or maintained and may be removed in a future release.

/** 
 * @deprecated Use the new {@link Control} base class instead.
 */
const getMembers = async () => await axios.get('get/members');

@defaultValue: Used to document the default value for a field or property, if a value is not assigned explicitly (In case the value is optional).

enum ViewType {
  Drawer = 'Drawer',   
  Modal = 'Modal',   
  Text = 'Text' 
};  
interface MemberForm {   
  /**    
   * @defaultValue    
   * ViewType.Modal   
   */   
  viewType?: ViewType; 
}

@example: Used to document an example of the function with a code sample.

/**
 * Adds two numbers together.  
 * @example { add two positive numbers }
 * add(1,1) // prints "2"
 * 
 * @example { add two negative numbers }
 * add(-1,-1) // prints "-2"
 */ 
export const add = (x: number, y: number): number => x + y;

@experimental, @beta, @alpha, @public

These tags represent software release life cycle.

• @experimental: Same as @beta, but used by tools that don’t support an @alpha release stage.
• @alpha: In case of alpha release phase.
• @beta: In case of beta release phase.
• @public: In case of stable release phase.

What is software release life cycle?

A software release life cycle represents the stages of software development. You might be familiar with the terminologies like alpha, beta, or stable(production).

• alpha: the first phase of software testing. The developers usually test the software using white-box, black-box or gray-box techniques and it is not thoroughly tested by the developer before it is released to customers.
• beta: The phase following alpha and it begins when the software is feature complete but likely to contain a number of known or unknown bugs.
• stable(production): The last phase which has passed all verifications and tests. This release goes to production.

@link: Used to create a hyperlink for references.

/**  
 * {@link https://github.com/microsoft/tsdoc}  
 * {@link Button}  
 * {@link my-control-library#Button | the Button class}  
 */

@override, @virtual

• @override: In case a member function or property is overriding the definition inherited from the parent class.
• @virtual: The parent class definition is be marked as @virtual

class Parent {   
  /** @virtual */   
  public render(): void {} 
}  
class Child extends Parent {   
  /** @override */   
  public render(): void; 
}

@param, @returns

• @param: Used to document a function parameter.
• @returns:Used to document a function’s return value.

/**  
 * @description Returns the average of two numbers.  
 * @param x - The first input number  
 * @param y - The second input number  
 * @returns The arithmetic mean of `x` and `y`  
 *  
 */ 
const getAverage = (x: number, y: number): number => (x + y) / 2.0;

@readonly: Used to document in case the value is readonly.

class Book {   
  /**    
   * @readonly    
   */   
   public getTitle(): string {     
     return this._title;   
   }    
   public setTitle(value: string) {     
     throw new Error('This property is read-only!');   
   } 
}

@remarks, @description, @summary: Used to document a description or summary about a function.

/**
 * @summary 
 * This component is a form for login.
 * @see { LogInInput.tsx, LogInButton.tsx }
 */
const LogInForm = () => {//...}

@see: Used to represent references which provide an information.

/**  
 * @see {@link ParsedUrl} for the returned data structure  
 * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}  
 * @see Component.tsx  
 */ 
function parseURL(url: string): ParsedUrl;

Conclusion

One day, I read an article saying that most developers use their time 90% to read and analyze existing code and 10% to write. Code commenting is helpful, especially in the case of the complicated and gigantic codebase.