0

I've defined a custom type via @typedef:

/**
 * @typedef {Object} FILE_DATA
 * @property {NodeJS.ReadableStream} fileStream
 * @property {string} fileUUID
 */

Then I apply this custom type in a method signature:

/**
 * Upload file to Dropbox
 *
 * @param {FILE_DATA} fileData - file data to be stored
 * @returns {Promise<Readonly<{fileName: string, folderUUID: string, isSucceeded: boolean, message: string}>>} file upload result
 */
export const fileUpload = async function fileUpload(fileData) {…}

When I generate a JSDoc, I expect that fileUpload() documentation will contain a custom type, in fact the only documentation about fileUpload() is:

(static, constant) fileUpload
Upload file to Dropbox

How to make JSDoc showing more details about fileUpload()?

Mike
  • 14,010
  • 29
  • 101
  • 161

1 Answers1

0

To solve the issue it's important to add an annotation @function/@method to the function fleUpload:

/**
 * Upload file to Dropbox
 *
 * @function
 * @param {FILE_DATA} fileData - file data to be stored
 * @returns {Promise<Readonly<{fileName: string, folderUUID: string, isSucceeded: boolean, message: string}>>} file upload result
 */
export const fileUpload = async function fileUpload(fileData) {

Once I've added this annotation, JSDoc puts fileUpload under the methods and not members.

Mike
  • 14,010
  • 29
  • 101
  • 161
  • Doesn't refactoring your code to `export async function fileUpload(fileData) { ... }` negate the need for `@method` ? The initial variable assignment seems unnecessary. – RobC Jul 31 '20 at 10:42
  • I've decided to use strict named function expressions over function declarations to gain more control over a code, e.g. no hoisting, therefore the code refactoring to `export async function fileUpload(fileData) { ... }` isn't so relevant for my use case. – Mike Jul 31 '20 at 11:08
  • OK, that's fair enough. In which case I can only assume `fileUpload` is used elsewhere in the same file (even though it's being `export`'ed), or maybe the functions body references outer variables/functions - otherwise the decision to use _"strict named function expressions over function declarations"_ due to hoisting is moot. – RobC Jul 31 '20 at 12:13
  • 1
    @RobC, I use `export` to expose `fileUpload` outside the module, to be able to call the function from another module. For me, the key issue of migration to JS was its unpredictable (comparing to C/Java/C#) behavior that's why I decided to stick as much as possible to the most strict approach. – Mike Jul 31 '20 at 12:34