JSDoc - how to document region of code

Question

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.

Momently

Answer 1

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 ...

Dispersion

You are right about editors, I am using sublime, but I don't like my own commenting style with // so decided to use jsdoc, which is neat for reading as well as I can generate doc for my app. – Momently

Answer 2

The SAPUI5: UI Development Toolkit for HTML5 documentation talks of the pitfalls of section/banner comments in JSDocs. Specifically:

JSDoc interprets any multiline comment starting with a double asterisks ( /** ) as a documentation comment for the JavaScript symbol that follows the documentation comment. [...] So do not use stars/asterisks for a separating banner comment. You can use other characters, for example

/* ==== */ 

or

/* ----- */

or at least avoid the double asterisks at the beginning.

Punchinello