how to generate documentation jsdoc

Navigation Menu

Search code, repositories, users, issues, pull requests..., provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications You must be signed in to change notification settings

An API documentation generator for JavaScript.

jsdoc/jsdoc

Folders and files, repository files navigation.

Want to contribute to JSDoc? Please read CONTRIBUTING.md .

Installation and Usage

JSDoc supports stable versions of Node.js 8.15.0 and later. You can install JSDoc globally or in your project's node_modules folder.

To install the latest version on npm globally (might require sudo ; learn how to fix this ):

To install the latest version on npm locally and save it in your package's package.json file:

Note : By default, npm adds your package using the caret operator in front of the version number (for example, ^3.6.3 ). We recommend using the tilde operator instead (for example, ~3.6.3 ), which limits updates to the most recent patch-level version. See this Stack Overflow answer for more information about the caret and tilde operators.

If you installed JSDoc locally, the JSDoc command-line tool is available in ./node_modules/.bin . To generate documentation for the file yourJavaScriptFile.js :

If you installed JSDoc globally, run the jsdoc command:

By default, the generated documentation is saved in a directory named out . You can use the --destination ( -d ) option to specify another directory.

Run jsdoc --help for a complete list of command-line options.

Templates and tools

The JSDoc community has created templates and other tools to help you generate and customize your documentation. Here are a few of them:

• jaguarjs-jsdoc
• DocStrap ( example )
• jsdoc3Template ( example )
• docdash ( example )
• tui-jsdoc-template ( example )
• better-docs ( example )

Build tools

• JSDoc Grunt plugin
• JSDoc Gulp plugin
• JSDoc GitHub Action

Other tools

• jsdoc-to-markdown
• Integrating GitBook with JSDoc

For more information

• Documentation is available at jsdoc.app .
• Contribute to the docs at jsdoc/jsdoc.github.io .
• Join JSDoc's Slack channel .
• Ask for help on the JSDoc Users mailing list .
• Post questions tagged jsdoc to Stack Overflow .

JSDoc is copyright (c) 2011-present Michael Mathews [email protected] and the contributors to JSDoc .

JSDoc is free software, licensed under the Apache License, Version 2.0. See the LICENSE file for more details.

Code of conduct

Releases 11, used by 180k.

Contributors 83

• JavaScript 99.4%

Code documentation for JavaScript with JSDoc: an introduction

Writing documentation for the source code can help your future self and your colleagues. Learn how to document JavaScript with JSDoc!

Why code documentation?

Suppose you wrote a couple of functions for making an HTML table with JavaScript. You could use those function right now, or pass them to another developer.

Everything is clear in your mind the moment you write the code, yet a month later you don't remember how to use functionA or functionB anymore. And so your colleagues. How functionA is supposed to be called? What parameters it takes ? And what shape should the parameters have?

Code documentation dissolves those doubts , helping you and other developers to understand how to use the software you wrote .

How many forms of code documentation?

There are many ways for documenting a piece of code. For example you can write:

• howtos guides for using your code
• a nice README for the repo
• code documentation in the source

Tutorials are nice because you can teach things to thousands of people, but they get outdated soon for many reasons: lack of time, breaking changes to the code.

A README on the Git repo hopefully is more in sync with the project because when you make changes to the code you're "forced" to update the README too (otherwise users will complain).

But on top of howtos and READMEs, code documentation in the source holds most of the value . It sits right there with the code and helps avoiding mistakes as you write JavaScript (or any other language) in the editor.

Speaking of JavaScript, we can use a documentation layer called, JSDoc . It's a command line tool and a "documentation language" at the same time. Let's see how it can helps.

JavaScript With JSDoc: first steps

JSDoc is a nice "language" for adding documentation to JavaScript. Consider the following function:

This function kind of speaks by itself, "generateTableHead" after all is a descriptive sentence. But how about the "data" parameter? What "data" should be really? If I look at the function's body becomes evident that "data" must be an array (by the way, what a bad naming for "data". How about "arrayOfNames"?).

"table" is less bad on the other hand, yet it's not clear if it could simply be a string or an actual HTML element.

Turns out, code documentation with JSDoc annotations can help our functions to better describe their intentions .

First thing first what's the anatomy of a JSDoc annotation ? JSDoc is simple as adding a comment before the function:

"Generates a table head", what a silly comment Valentino. We already know the function's purpose by looking at its name. But let's make things interesting with JSDoc annotations for function parameters . Here's the syntax:

For each parameter you can describe:

• its type , i.e. string, number, HTMLTableElement and so on
• a description

It may look weird to you now, but types are actually a thing in JavaScript: there are "stock" JavaScript types with their infamous coercion and strong types with TypeScript.

TypeScript is a slightly advanced topic , but when you define types with JSDoc in the documentation you're using a touch of "strong types" .

Having laid the foundations let's move on to documenting our function .

JavaScript With JSDoc: getting serious

"generateTableHead" should take an HTMLTableElement and an array as parameters . We can add annotations for both like so:

Adding JSDoc documentation has a side effect . Auto completion will improve in your IDE and you'll get real-time hints :

Moreover, the editor will scream if you try to pass the wrong kind of parameters :

The details for auto completion may vary from product to product, being fond of Webstorm I'm a bit biased here, of course you can get similar results with Vscode and friends.

It might sound crazy, but adding JSDoc annotations before writing the code, not after, is another thing you can do . And it has two nice outcomes. First, you will probably write better, simpler code because of the idea of it you formed while writing the documentation .

Also, you'll choose better names for parameters (unlike my "data"), variables, and functions too . Give it a shot and let me know if it changes your workflow!

JavaScript With JSDoc: more tags

JSDoc has a lot more tags. The "author" annotation for example is useful when you need to blame someone's else code. Here's an example:

Another useful tag is "return" (or "returns") for describing the return value of a function . Here's a function which returns nothing (i.e. a function whose job is printing to the console or creating an HTML element):

Notice the "void" return "type". To conclude here's a function which returns a number:

JSDoc works beautifully when you specify types in the doc , but you're also free to omit them. However by doing so you'll loose all the benefits. So that's all with JSDoc? Not yet! It can do another nice thing. Head over the next section!

P.S.: There are a lot more tags available for JSDoc. Check out the documentation here .

JavaScript With JSDoc: generating the docs

JSDoc has a binary which can be installed in your JavaScript project. To make a bit of practice create a project in a new folder:

Initialize with:

And install JSDoc:

Now create a new file named table.js with the following code:

Finally run the JSDoc binary against the file:

If everything goes well you'll see a new folder named out in your project folder. Inside this folder open up index.html, click on "generateTableHead" and check out the page:

You should see your documentation for generateTableHead formatted in HTML. Neat!

JSDoc is configurable , and of course you can place it in an NPM script for convenience.

Frequent objections to code documentation

"i don't see any value in adding documentation to my code. why should i bother".

I see where you're coming from! For typed languages like Java or TypeScript adding types to parameters in the documentation would be redundant. Consider the following example in TypeScript:

It's already evident from the code itself that both parameters are strings. There is no need to repeat types in JSDoc . Here's the suggested approach instead:

Still looks a bit redundant but JSDoc won't make any harm there.

JavaScript With JSDoc: wrapping up

Code documentation is often overlooked and considered more or less a waste of time. I suggest you to not follow bad advices. Instead you may want to learn how to document the code in your early days and make an habit from that .

"Great code should speak for itself" most developers will say. And that's true to some extents. Code should be clear, understandable plain english (I wish it was that simple). In reality code is still "machine" language and reading the intentions by simply looking at the source remains a dream .

Writing documentation for your code can help your future self and your colleagues. But it's not all bells and whistles . Documentation can become a burden really quick , getting soon out of sync from the actual code .

In that regard there are a lot of similarities with Test-Driven Development. First, both documentation and testing require great self-discipline . Second, writing them preemptively is really hard when you don't know how the implementation should look like .

On the other hand, it is really that hard to add documentation after finishing a method or class? That's where tools like JSDoc come in handy .

Thanks for reading and stay tuned on this blog!

Hi! I'm Valentino! I'm a freelance consultant with a wealth of experience in the IT industry. I spent the last years as a frontend consultant, providing advice and help, coaching and training on JavaScript, testing, and software development. Let's get in touch!

More from the blog:

• Formatting dates in JavaScript with Intl.DateTimeFormat
• A mostly complete guide to error handling in JavaScript.
• How babel preset-env, core-js, and browserslistrc work together
• You might not need switch in JavaScript
• How to build an URL and its search parameters with JavaScript
• var, let, and const in JavaScript: a cheatsheet.
• Cos'è JavaScript e perché studiarlo?
• All I need to know about ECMAScript modules
• What does it mean "event-driven" in JavaScript and Node.js?
• A look at generator functions and asynchronous generators in JavaScript.

How to Document JavaScript Code Using JSDoc

Proper code documentation is vital for maintainability. Using JSDocs, you can embed it right inside your code so it’s always at hand.

Proper code documentation is an important yet often overlooked aspect of software development. As a developer, you’ll be used to writing clean, efficient code, but you may be less experienced at writing good documentation.

Good documentation is useful for anyone working with your code, whether it’s other members of your team, or you, yourself, at a later date. It can explain why you’ve implemented something a particular way or how to use a particular function or API.

For JavaScript developers, JSDoc is a good way to start documenting your code.

What Is JSDoc?

Documenting code can be complex and tedious. However, more people are recognizing the benefits of a “docs as code” approach , and many languages have libraries that help automate the process. For simple, clear, and concise documentation. Just like the Go language has GoDoc to automate documentation from code, so JavaScript has JSDoc.

JSDoc generates documentation by interpreting special comments in your JavaScript source code, processing these comments, and producing bespoke documentation. It then makes this documentation available in an accessible HTML format.

This keeps the documentation within the code, so when you update your code, it's easy to update the documentation.

Setting Up JSDoc

The creators of JSDoc have made it easy to get started and set up JSDoc in your JavaScript project.

To install JSDoc locally, run:

This will install the library in your project as a dev dependency.

How to Write JSDoc Comments

To use JSDoc, you will use special syntax comments inside your source code. You will write all your documentation comments within /** and */ markers. Inside these, you can describe defined variables, functions, function parameters, and a lot else.

For example:

The @param and @returns tags are two of the many special keywords that JSDoc supports to explain your code.

To generate the documentation for this code, run npx jsdoc followed by the path to your JavaScript file.

If you installed JSDoc globally, you can omit the npx flag and run:

This command will generate an out folder in your project root. Inside the folder, you will find HTML files representing the pages of your documentation.

You can view the documentation by setting up a local web server to host it , or simply by opening the out/index.html file inside a browser. Here’s an example of what a documentation page will look like by default:

Configuring the JSDoc Output

You can create a configuration file to change JSDoc’s default behavior.

To do so, create a conf.js file and export a JavaScript module inside this file.

Inside the configuration file are various JSDoc configuration options. The template option lets you use a template to customize the documentation’s appearance. JSDoc’s community provides many templates that you can use. The package also allows you to create your own personalized templates.

To change the location of the generated documentation, set the destination config option to a directory. The example above specifies a docs folder in the project’s root.

Use this command to run JSDoc with a configuration file:

To make it easier to run this command, add it as a scripts entry inside your package.json file:

You can now run the npm script command inside a terminal.

An Example of Documentation Generated With JSDoc

Below is a simple arithmetic library with add and subtract methods.

This is an example of well-documented JavaScript code:

The JSDoc comments provide a clear and comprehensive description of the library and its methods, including:

• A description of the library and its purpose.
• Each method’s parameters, including their type and a brief description.
• The value and type that each method returns.
• The errors that each method can throw and the conditions that cause it.
• An example of how to use each method.

The comments also include the @module tag to indicate that this file is a module and the @example tag to provide a code example for each method.

Documenting Developer Code the Right Way

As you can see, JSDoc is a very useful tool to get you started documenting JavaScript code. With its easy integration, you can generate quick and detailed documentation as you write your code. You can also maintain and update the documentation right in your workspace.

However, as useful as JSDoc’s automation is, you should still adhere to certain guidelines so you can create quality documentation.

Mastering JSDoc: complete guide for Javascript developers

April 23, 2023 / 9 min read

Introduction

As Javascript developers, we all understand the importance of writing clean, readable, and maintainable code. One of the ways we can achieve this is by documenting our code properly. That’s where JSDoc comes into play .

JSDoc is a markup language used to describe the structure and behavior of Javascript code. It provides a standard way of documenting code so that other developers can easily understand what each function, method, or class does, its input parameters, return values, and more.

JSDoc is especially important in larger projects with multiple developers or contributors, where maintaining a clear and concise documentation of the codebase is crucial. It helps avoid confusion, misunderstandings, and errors by making the code more transparent, consistent, and self-explanatory.

In this blog post, we’ll cover the basics of JSDoc, its benefits , best practice , and how to integrate it with other tools. We’ll also provide real-world examples to help you understand how to use JSDoc effectively in your projects.

Basic Syntax of JSDoc

JSDoc is based on the same syntax as regular Javascript comments , with the addition of special tags and annotations to provide more structured documentation. Here’s how to use JSDoc annotations to document your code.

To add JSDoc to a function, class, or method, simply add a comment block above the declaration, starting with the /** characters. Here’s an example:

In the above example, we’ve used the @param tag to describe the input parameters of the sum() function and the @returns tag to describe its return value.

Here’s a brief overview of some commonly used JSDoc tags and their purpose:

• @param : describes a function or method’s input parameters, including their data type, name, and description.
• @returns : describes the value returned by a function or method, including its data type and description.
• @throws : describes the error or exception thrown by a function or method, including its data type and description.
• @deprecated : indicates that a function or method is no longer recommended for use and provides an alternative if available.
• @example : provides an example of how to use a function or method. Here are some practical examples of JSDoc annotations and tags:

By using JSDoc annotations and tags like in the above examples, we can make our code more understandable and maintainable. In the next section, we’ll discuss the benefits of using JSDoc in our projects.

Benefits of Using JSDoc

There are several benefits to using JSDoc in your Javascript projects. Let’s take a closer look at some of the key advantages:

Improved Code Documentation and Clarity

One of the most significant benefits of JSDoc is that it makes code documentation more consistent and easier to understand . By using standardized annotations and tags, developers can provide clear and concise descriptions of what a function or method does, its input parameters, and expected output.

For example, consider this function that calculates the area of a circle:

With JSDoc annotations, we can easily see that this function takes a numeric radius parameter and returns a numeric value representing the area of the circle . This information is especially helpful for team members who may not be familiar with the code or are new to the project.

Easier Maintenance and Debugging

JSDoc can also make maintenance and debugging easier by providing context for how code works . By documenting the behavior and inputs of each function or method, developers can more easily identify bugs, errors, or inconsistencies in the codebase.

For example, consider this function that converts a temperature from Celsius to Fahrenheit:

Better Understanding of Codebase

JSDoc can also help new developers or contributors better understand the codebase. By providing clear and concise documentation for each function, method, or class, developers can more easily navigate and understand the codebase.

For example, consider this class that represents a rectangle:

With JSDoc annotations, we can easily see that this class represents a rectangle, has a constructor that takes two numeric parameters for width and height , and a method calculateArea() that returns the area of the rectangle . This information can be very helpful for new developers or contributors who are trying to understand the functionality of the codebase.

Best Practices for Using JSDoc

JSDoc is a powerful tool that can help you document your Javascript code effectively, but to get the most out of it, it’s important to follow some best practices . Here are some tips to help you use JSDoc efficiently in your projects:

Consistency in JSDoc Style and Formatting

Consistency in style and formatting is essential for creating a clear and readable JSDoc documentation. It’s important to establish a consistent style and format across your codebase to make it easier for other developers to read and understand your code.

Here’s an example of a function with consistent JSDoc formatting:

Keeping JSDoc Up-to-Date with Code Changes

It’s important to keep your JSDoc annotations up-to-date with your code changes. Whenever you modify a function or method , make sure to update its corresponding JSDoc annotations.

Here’s an example of a modified function and its updated JSDoc annotations:

Utilizing JSDoc to Describe Complex Code Behavior and Logic

JSDoc can also be used to describe complex code behavior and logic that may not be immediately apparent from the code itself. This can help other developers understand how a function or method works and what it does under different conditions.

Here’s an example of a complex function with JSDoc annotations:

Integrating JSDoc with Other Tools

JSDoc can be integrated with various tools to further improve your development workflow. Here are some examples:

Editors and IDEs

Many modern editors and IDEs provide support for JSDoc, making it easier to write and maintain JSDoc annotations directly in your code. Let’s take Visual Studio Code as an example.

To get started with JSDoc in Visual Studio Code, install the Document This extension , which automatically generates JSDoc annotations for your code based on the function signature.

Documentation Generators

Finally, JSDoc can be used to generate documentation for your code using tools like JSDoc itself and TypeDoc . These tools generate HTML or Markdown documentation based on your JSDoc annotations, making it easier for others to understand how your code works and how to use it.

Here’s an example of how to use JSDoc to generate documentation for a function using the JSDoc CLI:

You can then run the JSDoc CLI to generate documentation for the calculator module:

This will generate HTML documentation in a out/ directory, which you can open in your browser to view the documentation.

In conclusion, JSDoc is an essential tool for Javascript developers who want to write clean, maintainable, and understandable code. By providing a standard way of documenting code, JSDoc helps improve code quality , productivity, and collaboration among team members.

By adopting JSDoc, you’ll not only make your code more transparent and understandable for other developers, but you’ll also improve your own coding skills by thinking more deeply about your code structure, behavior, and intent. So let’s make JSDoc a part of our coding best practices and write better code together.

DEV Community

Posted on Mar 3

Learn how to document JavaScript/TypeScript code using JSDoc & Typedoc

In this blog, you'll learn how to document your JS/TS code, how to give more context to your functionalities using JSDoc, and how to generate documentation files using Typedoc.

Setting up the project

Create a new project using npm:

For this blog I've created a small app ( download code ) containing 3 files:

• src/models/user.mjs
• src/models/todo.mjs

Then update the package.json file to use ES Modules:

Basic Todo class

Basic user class.

A user holds a list of Todos.

Now let's put them together. Back in app.js create an instance of user, followed by an instance of todo.

Now assign this todo to a user:

If you run the app (using npm start ), you should see user todos printed in the console:

Adding Docs

If you hover over the Todo or User class, there is very little information about either class.

And since JavaScript doesn't have type safety, there is no IntelliSense to tell you what methods are available on the object and what parameters you can pass to them.

This is where JSDoc comes to save the day.

In JavaScript, you can generate docs by simply typing /** and hitting enter. The Visual Studio Code then sets up a wrapper:

Inside you can describe your classes, interfaces, functions, their properties, and return types however you like:

Now if you hover over the User class you should see more info.

This is also applied to the methods that you document:

How cool is that?

Now let's add TypeDoc - Documentation generator for TypeScript. That said, you need to initialize a TypeScript project:

Setting up TypeScript

Now paste the following config into the newly generated tsconfig.json file:

Changing file structure

Now rename all your .js / .mjs files to .ts :

• src/models/user.ts
• src/models/todo.ts

Also be sure to remove the "type": "module" from the package.json file as that can confuse Node.js when running the files.

Fixing formatting

TypeScript will complain about the lack of "types" in the files. Here are the changed files:

Running the app (TS)

You need to install ts-node to run the Typescript files:

Now add ts-node to the start script in the package.json file:

Running the app using npm start should print the same result as before.

Adding TypeDoc

Firstly, install Typedoc using npm:

Then update the tsconfig.json file with Typedoc configuration:

Lastly, add a script that is used from running Typedoc

Run the script using:

This will generate HTML docs page in the specified path ( "out": "docs/typedoc" ) that you can open in your web browser.

More complex projects will have better-detailed docs.

That's all from me today. If you'd like to learn more make sure to check out my other blog as well on Medium and follow me on Twitter to stay up to date with my content updates.

Bye for now 👋

Top comments (3)

Templates let you quickly answer FAQs or store snippets for re-use.

• Email [email protected]
• Location Germany
• Work Senior Frontend Developer at CrabNebula
• Joined Jun 13, 2017

One of my favorite tricks is using markdown in JSDoc comments, as it is supported by virtually all IDEs and editors with JSDoc support.

• Joined Feb 26, 2018

Really? I haven't tried that. Thanks for the input

• Email [email protected]
• Location Jaipur, Rajasthan, India
• Education Metric
• Pronouns Gautam
• Joined Sep 18, 2022

The typescript one is awesome 😍😍😍

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink .

Hide child comments as well

For further actions, you may consider blocking this person and/or reporting abuse

Performance em Aplicações React: Dicas e Técnicas de Otimização

Vitor Rios - May 9

👥 Reproducible Nx Workspace with HugeNx’s Conventions

jogelin - May 5

Features, future-proof and interoperable in TiniJS apps

Nhan Lam - May 4

How to set up a new project using Yarn

Anton Prudkohliad - May 8

We're a place where coders share, stay up-to-date and grow their careers.

• 15 Dependencies
• 936 Dependents
• 50 Versions

An API documentation generator for JavaScript.

Want to contribute to JSDoc? Please read CONTRIBUTING.md .

Installation and Usage

JSDoc supports stable versions of Node.js 12.0.0 and later. You can install JSDoc globally or in your project's node_modules folder.

To install the latest version on npm globally (might require sudo ; learn how to fix this ):

To install the latest version on npm locally and save it in your package's package.json file:

To install the latest development version locally, without updating your project's package.json file:

If you installed JSDoc locally, the JSDoc command-line tool is available in ./node_modules/.bin . To generate documentation for the file yourJavaScriptFile.js :

If you installed JSDoc globally, run the jsdoc command:

By default, the generated documentation is saved in a directory named out . You can use the --destination ( -d ) option to specify another directory.

Run jsdoc --help for a complete list of command-line options.

Templates and tools

The JSDoc community has created templates and other tools to help you generate and customize your documentation. Here are a few of them:

• jaguarjs-jsdoc
• DocStrap ( example )
• jsdoc3Template ( example )
• docdash ( example )
• tui-jsdoc-template ( example )
• better-docs ( example )

Build tools

• JSDoc Grunt plugin
• JSDoc Gulp plugin

Other tools

• jsdoc-to-markdown
• Integrating GitBook with JSDoc

For more information

• Documentation is available at jsdoc.app .
• Contribute to the docs at jsdoc/jsdoc.github.io .
• Join JSDoc's Slack channel .
• Ask for help on the JSDoc Users mailing list .
• Post questions tagged jsdoc to Stack Overflow .

JSDoc is copyright (c) 2011-present Michael Mathews [email protected] and the contributors to JSDoc .

JSDoc is free software, licensed under the Apache License, Version 2.0. See the file LICENSE.md in this distribution for more details.

• documentation

Package Sidebar

npm i jsdoc

Git github.com/jsdoc/jsdoc

github.com/jsdoc/jsdoc#readme

Downloads Weekly Downloads

Unpacked size, total files, last publish.

a month ago

Collaborators

Configuring JSDoc with a configuration file

Configuration file formats.

To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats:

• A JSON file. In JSDoc 3.3.0 and later, this file may include comments.
• A CommonJS module that exports a single configuration object. This format is supported in JSDoc 3.5.0 and later.

To run JSDoc with a configuration file, use the -c command-line option (for example, jsdoc -c /path/to/conf.json or jsdoc -c /path/to/conf.js ).

The following examples show a simple configuration file that enables JSDoc's Markdown plugin . JSDoc's configuration options are explained in detail in the following sections.

For a more comprehensive example of a JSON configuration file, see the file conf.json.EXAMPLE .

Default configuration options

If you do not specify a configuration file, JSDoc uses the following configuration options:

This means:

• No plugins are loaded ( plugins ).
• If recursion is enabled with the -r command-line flag , JSDoc will search for files 10 levels deep ( recurseDepth ).
• Only files ending in .js , .jsdoc , and .jsx will be processed ( source.includePattern ).
• Any file starting with an underscore, or in a directory starting with an underscore, will be ignored ( source.excludePattern ).
• JSDoc supports code that uses ES2015 modules ( sourceType ).
• JSDoc allows you to use unrecognized tags ( tags.allowUnknownTags ).
• Both standard JSDoc tags and Closure Compiler tags are enabled ( tags.dictionaries ).
• Inline {@link} tags are rendered in plain text ( templates.cleverLinks , templates.monospaceLinks ).

These options and others are explained in the following sections.

Configuring plugins

To enable plugins, add their paths (relative to the JSDoc folder) into the plugins array.

For example, the following JSON configuration file will enable the Markdown plugin, which converts Markdown-formatted text to HTML, and the "summarize" plugin, which autogenerates a summary for each doclet:

See the plugin reference for further information, and look in JSDoc's plugins directory for the plugins built into JSDoc.

You can configure the Markdown plugin by adding a markdown object to your configuration file. See Configuring the Markdown Plugin for details.

Specifying recursion depth

The recurseDepth option controls how many levels deep JSDoc will recursively search for source files and tutorials. This option is available in JSDoc 3.5.0 and later. This option is used only if you also specify the -r command-line flag , which tells JSDoc to recursively search for input files.

Specifying input files

The source set of options, in combination with paths given to JSDoc on the command line, determines the set of input files that JSDoc uses to generate documentation.

• source.include : An optional array of paths that contain files for which JSDoc should generate documentation. The paths given to JSDoc on the command line are combined with these paths. You can use the -r command-line option to recurse into subdirectories.
• source.exclude : An optional array of paths that JSDoc should ignore. In JSDoc 3.3.0 and later, this array may include subdirectories of the paths in source.include .
• source.includePattern : An optional string, interpreted as a regular expression. If present, all filenames must match this regular expression to be processed by JSDoc. By default, this option is set to ".+\.js(doc|x)?$", meaning that only files with the extensions .js , .jsdoc , and .jsx will be processed.
• source.excludePattern : An optional string, interpreted as a regular expression. If present, any file matching this regular expression will be ignored. By default, this option is set so that files beginning with an underscore (or anything under a directory beginning with an underscore) is ignored.

These options are interpreted in the following order:

• Start with all paths given on the command line and in source.include .
• For each file found in Step 1, if the regular expression source.includePattern is present, the filename must match it, or it is ignored.
• For each file left from Step 2, if the regular expression source.excludePattern is present, any filename matching this regular expression is ignored.
• For each file left from Step 3, if the file's path is in source.exclude , it is ignored.

All remaining files after these four steps are processed by JSDoc.

As an example, suppose you have the following file structure:

In addition, suppose your conf.json file looks like this example:

If you run jsdoc myProject/c.js -c /path/to/my/conf.json -r from the file containing the myProject folder, JSDoc will generate documentation for the following files:

• myProject/a.js
• myProject/c.js
• myProject/lib/a.js

Here's why:

• myProject/c.js (from the command line)
• myProject/a.js (from source.include )
• myProject/lib/a.js , myProject/lib/ignore.js , myProject/lib/d.txt (from source.include and using the -r option)
• myProject/_private/a.js (from source.include )
• JSDoc applies source.includePattern , leaving us with all of the above files except myProject/lib/d.txt , which does not end in .js , .jsdoc , or .jsx .
• JSDoc applies source.excludePattern , which removes myProject/_private/a.js .
• JSDoc applies source.exclude , which removes myProject/lib/ignore.js .

Specifying the source type

The sourceType option affects how JSDoc parses your JavaScript files. This option is available in JSDoc 3.5.0 and later. This option accepts the following values:

• module (default): Use this value for most types of JavaScript files.
• script : Use this value if JSDoc logs errors such as Delete of an unqualified identifier in strict mode when it parses your code.

Incorporating command-line options into the configuration file

You can put many of JSDoc's command-line options into the configuration file instead of specifying them on the command line. To do this, add the long names of the relevant options into an opts section of the configuration file, with the value set to the option's value.

By using the source.include and opts options, you can put almost all of the arguments to JSDoc in a configuration file, so that the command line reduces to:

When options are specified on the command line and in the configuration file, the command line takes precedence.

Configuring tags and tag dictionaries

The options in tags control which JSDoc tags are allowed and how each tag is interpreted.

The tags.allowUnknownTags property affects how JSDoc handles unrecognized tags. If you set this option to false , and JSDoc finds a tag that it does not recognize (for example, @foo ), JSDoc logs a warning. By default, this option is set to true . In JSDoc 3.4.1 and later, you can also set this property to an array of tag names that JSDoc should allow (for example, ["foo","bar"] ).

The tags.dictionaries property controls which tags JSDoc recognizes, as well as how JSDoc interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag dictionaries:

• jsdoc : Core JSDoc tags.
• closure : Closure Compiler tags .

By default, both dictionaries are enabled. Also, by default, the jsdoc dictionary is listed first; as a result, if the jsdoc dictionary handles a tag differently than the closure dictionary, the jsdoc version of the tag takes precedence.

If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that Closure Compiler does not recognize, change the tags.dictionaries setting to ["closure"] . You can also change this setting to ["closure","jsdoc"] if you want to allow core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.

Configuring templates

The options in templates affect the appearance and content of generated documentation. Third-party templates may not implement all of these options. See Configuring JSDoc's Default Template for additional options that the default template supports.

If templates.monospaceLinks is true, all link text from the inline {@link} tag will be rendered in monospace.

If templates.cleverLinks is true, {@link asdf} will be rendered in normal font if asdf is a URL, and monospace otherwise. For example, {@link http://github.com} will render in plain text, but {@link MyNamespace.myFunction} will be in monospace.

If templates.cleverLinks is true, templates.monospaceLinks is ignored.

Related links

• About JSDoc plugins
• Command-line arguments to JSDoc
• Using the Markdown plugin

• Artificial Intelligence /

Telegram gets an in-app Copilot bot

Microsoft copilot for telegram will only work with text-based requests for now..

By Emilia David , a reporter who covers AI. Prior to joining The Verge, she covered the intersection between technology, finance, and the economy.

Share this story

If you buy something from a Verge link, Vox Media may earn a commission. See our ethics statement.

Microsoft has added an official Copilot bot within the messaging app Telegram , which lets users search, ask questions, and converse with the AI chatbot. 

Copilot for Telegram is currently in beta but is free for Telegram users on mobile or desktop. People can chat with Copilot for Telegram like a regular conversation on the messaging app. Copilot for Telegram is an official Microsoft bot (make sure it’s the one with the checkmark and the username @CopilotOfficialBot). Several AI companies now let you access their LLMs through messaging apps. Meta added Meta AI to its chat apps, including Messenger, WhatsApp, and Instagram messaging, and you can chat with Gemini inside Google Messages on Android phones .

To access Copilot for Telegram, I first had to search for Copilot Bot. It then asked me to share my Telegram phone number with Microsoft, which felt weird considering I used to use Telegram specifically to talk to privacy-crazy crypto founders, and the app prides itself on its strict privacy policies .

Copilot for Telegram is not that much different from other Copilots, but it does have some limitations. It’s limited to text requests and cannot generate images. It can search the internet information. Microsoft says in a blog post that Copilot for Telegram can suggest movies to watch, generate a new workout routine, help with coding tasks, translate conversations, and find quick facts on the internet. There’s a daily 30-turn limit, meaning the user and Copilot can only have 30 back-and-forth exchanges.

Microsoft has been expanding its Copilots, bringing the AI assistant into many of its offerings. There are Copilots for business applications , PCs with built-in Copilots , Copilot for Microsoft 365 , and a paid version that gives access to the latest AI models for $20 a month.

Google won’t comment on a potentially massive leak of its search algorithm documentation

Google scrambles to manually remove weird ai answers in search, apple’s wwdc may include ai-generated emoji and an openai partnership, lego’s first legend of zelda set is a 2,500-piece great deku tree, microsoft confirms call of duty: black ops 6 is coming to xbox game pass.

More from Artificial Intelligence

OpenAI researcher who resigned over safety concerns joins Anthropic

Opera adds Google’s Gemini to its browsers

Chromebook Plus laptops are getting Google Gemini

OpenAI has a new safety team — it’s run by Sam Altman