Yamdog – Documentation Generator for JavaScript Modules

Years ago I used JSDoc to generate API docs – application programming interface documentation – for my JavaScript packages. Gradually I dropped the tool. I did not like how its syntax made the comment blocks look like another kind of code. Here is an example copied from JSDoc’s Getting Started guide:

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

Soon, I began writing my documenting comments in another, simpler way. That eventually led me to publish Yamdog – Yet Another Markdown API Docs Generator for JavaScript. Here is the same example written in yamdog syntax:

// library.shelf.Book(title, author)
//
// Represents a book.
//
// Parameters:
//   title
//     string. The title of the book.
//   author
//     string. The author of the book.
//
function Book(title, author) {
}

In contrast to JSDoc, Yamdog has no predefined keywords or tags. The structure is all that matters. For that, it recognises popular Markdown and YAML syntax. YAML provides nested, indentation-based list structures. In turn, Markdown offers further structures like images, tables, and hyperlinks, and rudimentary markup for emphasis like italics and bolding.

For example, here is some Markdown:

# Heading

A paragraph with **bold** and *italic* words
and a [hyperlink](http://www.example.com).

![An image](http://www.example.com/image.jpg)

And here is some YAML:

This is:
- a list in YAML
- a list with two list items

And here we have:
  some key:     some value
  another key:  another value

In addition to mere syntax, Yamdog is a tool that you need to run to generate a documentation for your JavaScript code. See Yamdog Usage for details. The output looks similar to the screenshot below, taken from Yamdog’s own API docs that are generated with Yamdog itself of course.

Soon after I published the yamdog package in July 2022, I began integrating it to multiple projects that screamed for better API reference docs, including Nudged, Affineplane, and Tapspace.

If you feel Yamdog could help you out in your documenting endeavours, travel to Yamdog homepage and give it a spin. If you face any issues or have ideas for improvement, let me know!