jsdoc rules for better packages reference docs

[mkucmus]

jsdoc rules

examples of how to make reference section better by following some jsdoc rules

Description

Use JSDoc: @description

Every function must contain a comment with general description of a purpose or main goal.

Can be placed as a first text in the function/type comment section or prefixed with @description tag later on.

/**
 * Get product url. The priority is SEO url and then technical url.
 */
export function getProductUrl(...

will become on function detail page:

and the same description will be used in index file:

Visibility

@public every function or type marked by this tag will be published and appear in a package reference table of functions:

@beta or nothing - won’t appear in reference index file.

Parameters

Use JSDoc: @param

In our case the @param tag is necessary in order to have an explanation what a specific parameter is used for:

/**
 * @param {Product | LineItem | OrderLineItem} object Object containing media object
 */

Will become:

If provided type like Product is defined in @shopware-pwa/types package, vitepress will try to link it to the corresponding file in GitHub repository. Otherwise it will remain a plain text like it does for types string or boolean and other primitive types.

Complex types

Every exported type should be also documented, especially defined properties and methods:

export type UseCheckoutReturn = {
  /**
   * Fetches all available shipping methods
   */
  getShippingMethods(options?: {
    forceReload: boolean;
  }): Promise<ComputedRef<ShippingMethod[]>>;
  /**
   * List of available shipping methods
   */
  shippingMethods: ComputedRef<ShippingMethod[]>;
  /**
   * Fetches all available payment methods
   */
  getPaymentMethods(options?: {
    forceReload: boolean;
  }): Promise<ComputedRef<PaymentMethod[]>>;
  /**
   * List of available payment methods
   */
  paymentMethods: ComputedRef<PaymentMethod[]>;

Will become:

if it’s a method (function)

for properties

Custom tags

@category

This tag is used to group functions in the groups to improve the readiness:

/**
* @category Product
*/

Will place a tagged function to Product section in index file of a package:

@NOLINK

Every function listed in a package index file is automatically linked to the function detail page:

getProductUrl from @shopware-pwa/helpers will be linked to: helpers/getProductUrl.md

If there is no need to create a specific detail page for a function, use @NOLINK tag in the function’s description to not link the function to the corresponding page. Otherwise there will be a warning during build time of vitepress documentation.

A good example is endpoints getters that are self-descriptive and there is nothing new to add.