Search code examples
javascriptcommentsjsdocregions

JSDoc - how to document region of code


I have started using of JSDoc and so far it is great thing, but I want to document the part of my code like Visual Studio has #region.

Should I just wrap it in block of comments like this?

/**
 * Region for calling express routes 
 */

here goes code...

/**
 * End region
 */

I am just searching more elegant way to do this.


Solution

  • JSDoc does not provide a similar option. IMHO it does not make much sense, either. How is it helpful in documenting an API or feeding some IDE' code assist?

    #region lets you specify a block of code that you can expand or collapse when using the outlining feature of the Visual Studio Code Editor. In longer code files, it is convenient to be able to collapse or hide one or more regions so that you can focus on the part of the file that you are currently working on.

    Even docs on #region remarks this is to enable a feature of the particular editor. JSDoc isn't bound to some editor but for helping with API documentations. By using a fairly convenient editor you don't need such comments but use the expanders provided by editor (e.g. Webstorm, Visual Studio Code).

    See http://usejsdoc.org for all available options.

    You might want to "force" editor to collapse some part of code separately. This could be achieved by wrapping it in some language object (collapsable in your favourite editor) or a pair of braces. However, if you will ever have to share this code expect the be asked about what this is good for ...