Jsdoc Config File

[Yaima President]

Todisable pretty-printed files, set the option templates.default.outputSourceFiles to false.Using this option also removes links to your source files from the documentation. This option isavailable in JSDoc 3.3.0 and later.

JSDoc's default template automatically copies a few static files, such as CSS stylesheets, to theoutput directory. In JSDoc 3.3.0 and later, you can tell the default template to copy additionalstatic files to the output directory. For example, you might want to copy a directory of images tothe output directory so you can display these images in your documentation.

By default, JSDoc's default template always shows the current date in the footer of the generateddocumentation. In JSDoc 3.3.0 and later, you can omit the current date by setting the optiontemplates.default.includeDate to false.

By default, JSDoc's default template shows a shortened version of each symbol's name in thenavigation column. For example, the symbol my.namespace.MyClass would be displayed simply asMyClass. To show the complete longname instead, set the optiontemplates.default.useLongnameInNav to true. This option is available in JSDoc 3.4.0 and later.

The default template uses a file named layout.tmpl to specify the header and footer for eachpage in the generated documentation. In particular, this file defines which CSS and JavaScript filesare loaded for each page. In JSDoc 3.3.0 and later, you can specify your own layout.tmpl file touse, which allows you to load your own custom CSS and JavaScript files in addition to, or insteadof, the standard files.

To use this feature, set the option templates.default.layoutFile to the path to your customizedlayout file. Relative paths are resolved against the current working directory; the path to theconfiguration file; and the JSDoc directory, in that order.

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

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

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

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

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, thejsdoc version of the tag takes precedence.

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

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

I had a similar issue. First, I verified that the file was encoded as UTF-8 via Notepad++. When that didn't work, based on the comment from Andreas, I simply copied and pasted my config code into the same file, saved, ranjsdoc -c jsdoc.conf and it worked. Hope this helps someone in the future.

I had this problem when I tried to feed it valid JSON, but in a file with .js extension. Silly mistake, I create a dynamic object and export it into a static json file before running JSDoc and forget to use .json extension for the created file. It gives Cannot parse the config file [...].js: SyntaxError: Unexpected token ':' which is a really bad error message. Hope it helps someone.

If you are not using TypeScript syntax (your source files are still .js files)but you are using the TypeScript flavor within JSDoc (i.e., the default"typescript" mode in eslint-plugin-jsdoc) and you are perhaps usingallowJs and checkJs options of TypeScript's tsconfig.json), you mayuse:

eslint-plugin-jsdoc options, if present, are generally in the form of anobject supplied as the second argument in an array after the error level(any exceptions to this format are explained within that rule's docs).

Note that a number of fixable rules have an enableFixer option which canbe set to false to disable the fixer (or in the case of check-param-names,check-property-names, and no-blank-blocks, set to true to enable anon-default-recommended fixer).

Now, to be honest, even though I've been using JSDoc comments to document my code for a long time, I didn't install this package until a few weeks ago because I didn't actually needed to generate the website. Instead I was just using it with VSCode, but I'll talk about that later in this post.

Remember, the more info you add to your comments, the more detailed your API documentation will be. But also, find the amount of detail that feels right to you. It's better to have all your code documented with only a few tags than to have only a few methods fully documented using all the tags because it was too much and you couldn't keep up.

It's likely that you're working on a big project with many files and folders that you want to export, and also some that you need to exclude (I'm looking at you, node_modules). If that's the case you may want to use a JSDoc Configuration file.

You can create your own template for your API documentation by generating a custom layout.tmpl file and setting the option templates.default.layoutFile to the path of your custom layout in your JSDoc configuration file.

Thanks for your post! jsdoc is very useful, a helpful and often underrated solution to improve vanilla JavaScript development, especially in small, mostly HTML / CSS based projects without complex JavaScript stuff (and without Babel transpilation) whete you don't necessarily need Typescript.

I found the JSDoc website a little ugly, but since JSDoc comment syntax is so widely used, I merged Vuepress and Documentation.js together. What I ended up doing is using the markdown docs from documentation.js and building them into a nice looking webpage with Vuepress. You can check it out here. However, I did have to write a small little script to add the metadata necessary for Vuepress to build it, however.

Configurations can be quite complex, and sometimes you may want to utilize the great type checking that TypeScript provided. Change your xxx.config.js to xxx.config.ts is not an ideal solutions as you will need to have a Node.js register involved to transpile it into JavaScript and some tools might not support doing that way. Fortunately, TypeScript also support type check in plain JavaScript file with JSDoc. Here is an example of Webpack config with type checks:

defineConfig exists in the runtime, so it works for JavaScript even if the types get truncated. This is really just some small details of DX, but I would wish more tools could adapt this approach and make the type checking more approachable and simpler.

Over the tree we have a few places where we use a couple of legacy ESLint rules for ensuring the correct formatting of jsdoc comments. We are now part way through transitioning the existing areas these across to use rules from the supported eslint-plugin-jsdoc plugin.

Initially we are focussing on transitioning the existing areas away from the legacy rules. Once that is complete, we'll think about how to roll this out to new areas - if anyone is interested in enabling this for their component, please let me know off-list or via #lint:mozilla.org on Matrix.

So it will be enabled by default. This requires the rest of the team to do the same IDE config (in case you're not working alone) and it can be escaped at file level by adding // @ts-nocheck at the top of a specific file.

The second one is just adding // @ts-check at the top of your file so this specific file will be checked by default from now on and cannot be escaped unless either you change it to // @ts-nocheck or you delete this line.

I think code documentation works best when it lives side by side with the code it is documenting rather than being written in a separate document. When it's separate, it becomes easy for documentation to become stale. Out of sight, out of mind!

However, documentation can be easier to read if it's nicely formatted rather than reading straight from the code editor. With this in mind, I started looking at JSDoc for documenting my JavaScript code. You simply write the documentation with your source code and then run a command to generate a static website build with nicely formatted documentation. Best of both worlds!

At the root of my repo I created a new folder at docs/jsdoc and changed into that directory in the console. Then I ran yarn init and followed the console steps to create a new package.json file. Then I ran yarn add jsdoc docdash --dev to install the required packages.

Keeping all of the documentation configuration in a subdirectory prevents polluting the main code base with additional configuration and keeps the node modules separate. Netlify supports deploying sites from within subdirectories so everything required to build a documentation site can be neatly organised in its own folder. I can also easily add other folders under docs for additional documentation sites, say for my view components as an example.

3a8082e126