documentation
documentation copied to clipboard
documentationjs
@returns object only support text, it does not provide a default return value formatted with code
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?
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.
