Stack Overflow
Stack Overflow

Questions tagged [jsdoc]

JSDoc is a markup language for adding inline API documentation to JavaScript source code. This is distinct from the various tools that parse and manipulate code that follows the JSDoc syntax.

The JSDoc markup language is similar to the Javadoc syntax, used for documenting Java code, but is specialized to work with JavaScript's more dynamic syntax and therefore unique, as it is not completely compatible with Javadoc. However, like Javadoc, JSDoc allows the programmer to create doclets and tags which can then be translated into published output, like HTML or RTF.

Example:

/**
    Represents a book.
    @constructor
    @param {string} title - The title of the book.
    @param {string} author - The author of the book.
 */
function Book(title, author) {
}

The following annotations are commonly used in modern JSDoc, but the full list varies between implementations:

  • @param Documents a method parameter; a datatype indicator can be added between curly braces
  • @return Documents a return value
  • @constructor Marks a function as a constructor
  • @deprecated Marks a method as deprecated
  • @private Signifies that a method is private
  • @requires Describe a required resource.
  • @this Specifies the type of the object to which the keyword "this" refers within a function.
  • @throws Documents an exception thrown by a method
  • @exception Synonym for @throws
  • @author Developer's name
  • @version Provides the version number of a library
1697 questions
77
votes
6 answers

JSDoc adding real code in documentation

Do you know if there is some sort of tag in JSDoc? I need to add pieces of code in my documentation like this: /** * This function does something see example below: * * var x = foo("test"); //it will show "test" message * * @param…
Marco Demaio
  • 33,578
  • 33
  • 128
  • 159
73
votes
5 answers

Enum as @param type in JSDoc

Is it possible to use an enum for the JSDoc @param type declaration like in the following example? /** * @enum { Number } */ const TYPES = { TYPE_A: 1, TYPE_B: 2 } /** * @param { TYPES } type */ function useTypesEnum( type ) { …
BuZZ-dEE
  • 6,075
  • 12
  • 66
  • 96
71
votes
1 answer

Mixing JavaScript and TypeScript in Node.js

While having parts of a Node.js in plain ES6, is it possible to mix in some Typescript modules within the same project? E.g. having some Types defined in TypeScript that are imported via require into plain ES6 files?
Alexander Zeitler
  • 11,919
  • 11
  • 81
  • 124
71
votes
6 answers

How to easily create Github friendly markdown for documented JavaScript functions?

I want to be able to take JSDoc comments like this anywhere in JavaScript source (even nested down several layers of functions, in a module or even anonymous functions): /** * Used to do some important thing that needs doing that works like xyz. …
jwl
  • 10,268
  • 14
  • 53
  • 91
69
votes
2 answers

jsdoc valid param types

Is there a list somewhere of valid types for param tags for jsdoc? For example, @param {type} myParam Some parameter description I know that things like number and String are valid, but what if I want to document that the number is an integer. Is…
Jeff Storey
  • 56,312
  • 72
  • 233
  • 406
66
votes
8 answers

How to annotate Express middlewares with JSDoc?

I'm trying to document an Express middleware, but the build-in validation tool in WebStorm tells me that types are incorrectly assigned in the following JSDoc block: /** * My middleware. * * @param {Object} req * @param {Object} res * @param…
Jun Thong
  • 669
  • 1
  • 5
  • 6
63
votes
3 answers

How to extend a typedef parameter in JSDOC?

Assuming you have the following code inside a ES6 class (documentation): /** * @typedef Test~options * @type {object.} * @property {array} elements - An array containing elements * @property {number} length - The array length */ /** *…
dude
  • 5,678
  • 11
  • 54
  • 81
57
votes
2 answers

How do you document JSDoc with mixed parameter type?

How do I document a method in JavaScript using JSDoc when the parameter type can be mixed? I have method on a Dialog object where I can show HTML or my own Viewable objects. The method JSDoc looks like this: /** * Can pass in viewable object, or…
Oliver Watkins
  • 12,575
  • 33
  • 119
  • 225
57
votes
3 answers

Document generic type parameters in JSDOC

In JSDoc there exists the possibility to document the exact types of array contents like this: /** @param {Array.} myClasses An array of MyClass objects. */ TestClass.protoype.someMethod = function( myClasses ){ …
Sebastian
  • 7,729
  • 2
  • 37
  • 69
55
votes
4 answers

How to document a function returned by a function using JSDoc

I am using JSDoc for parameter documentation. It is clear how to document the parameter types for many_prompts, but what is the right way to document the function it returns? /** * @param {Number} - number of times to prompt * @return…
Aminadav Glickshtein
  • 23,232
  • 12
  • 77
  • 117
51
votes
3 answers

How can I mark a parameter as containing a DOM node in JSDoc?

I want to indicate that a parameter should be a DOM node, but I can't seem to find any information about how to indicate that with JSDoc. I could just use {Object}, but that is rather ugly. I would much rather have something like {Node} or…
cdeszaq
  • 30,869
  • 25
  • 117
  • 173
50
votes
5 answers

What is the correct JSDoc syntax for a local variable?

For a function like this... function example() { var X = 100; ... var Y = 'abc'; ... return Z; } I need to explain the purpose of some of the local variables. Adding a description like this... function example() { /** *…
Kirkland
  • 2,319
  • 4
  • 20
  • 27
48
votes
4 answers

How do I JSDoc A Nested Object's Methods?

I've been trying to use JSDoc3 to generate documentation on a file, but I'm having some difficulty. The file (which is a Require.js module) basically looks like this: define([], function() { /* * @exports mystuff/foo */ var foo =…
machineghost
  • 33,529
  • 30
  • 159
  • 234
47
votes
5 answers

How to document CoffeeScript source code with JSDoc?

I have some code written in CoffeeScript and I want to optimize the generated JavaScript with the Google Closure Compiler, so these files need to be documented with JSDoc. My question is, how can I document the *.coffee files to generate javascript…
aztack
  • 4,376
  • 5
  • 32
  • 50
47
votes
1 answer

JSDoc: How do I document the "options" object literal for a parent "class"?

I am using jQuery's $.widget() base "class" which provides an option() method. Since the method is not in my code, I don't have a place to document the argument. I tried to put jsDoc on the fields in the default options literal, but they're simply…
billc.cn
  • 7,187
  • 3
  • 39
  • 79
1
2
3
…
99 100