@returns object only support text, it does not provide a default return value formatted with code

[kopax]

I have been trying to use @returns with an object and write the documentation.

I always get the same output, for instance:

* @returns {Object} result - The result state.
 * @returns {boolean} result.success - True if no errors.
 * @returns {boolean} result.generatedPdfFilePathList - List of generated PDF filepath.
 * @returns {Object} result.generatedLatexFilePathList - List of generated LaTeX filepath or undefined if nothing.
 * @returns {string} result.errors - List of errors or undefined if no errors.

It will not use <code> for result, after {object} everything is considered as text.

I have also tried:

 * @return {object} [result={
 *  success, // True if no errors.
 *  generatedPdfFilePathList, // List of generated PDF filepath.
 *  generatedLatexFilePathList, // List of generated LaTeX filepath or undefined if nothing.
 *  errors, // List of errors or undefined if no errors.
 * }] - The result object.

Same result.

This force us to write text while we wan't to describe the returned object:

 * @return {object} including success, generatedPdfFilePathList, generatedLatexFilePathList and errors

Is there a way to write documentation for this properly?

[tmcw]

The @returns implementation follows the JSDoc spec ( https://jsdoc.app/tags-returns.html ) which doesn't include default values or nesting. We could support a more expressive syntax here, but it'd need to be a non-standard extension of JSDoc.

[kopax]

It would be nice to allow this, we could recycle the @param behavior.