JSDuck is a Ruby-based documentation generator specifically designed for ExtJS and Sencha Touch applications. It extracts standard /… */ block comments directly from your JavaScript source code and turns them into interactive, searchable HTML documentation websites.
Below is a complete, step-by-step guide to installing, configuring, and generating documentation using JSDuck. 1. Installation
Because JSDuck is written in Ruby, you must have Ruby installed on your machine.
Via RubyGems (Mac/Linux/Windows): Open your terminal and install the gem globally: gem install jsduck Use code with caution.
Windows Alternative: If you do not have Ruby, you can download a standalone pre-compiled Windows binary executable directly from the official JSDuck GitHub repository. 2. Documenting Your Code (Syntax)
JSDuck reads special block comments that begin with two asterisks (/). It supports standard Markdown syntax inside the descriptions and leverages distinct tags to define structure. javascript
/ * @class MyProject.utils.Calculator * A simple utility class for basic arithmetic operations. * This description supports Markdown formatting. */ Ext.define(‘MyProject.utils.Calculator’, { singleton: true, /** * @method add * Adds two numbers together and returns the sum. * * @param {Number} a The first number to add. * @param {Number} b The second number to add. * @return {Number} The summation result. */ add: function(a, b) { return a + b; } }); Use code with caution. 3. Generating the Documentation
Once your code is annotated, you can invoke JSDuck via the command line to parse your directories and export the HTML output. Option A: Quick Command Line Build
To generate documentation instantly, specify your source directory (or multiple directories) and use the –output flag: jsduck my-project/js/ –output docs/ Use code with caution.
If you are using the ExtJS framework, you should pass both the ExtJS source folder and your project folder. This ensures your documentation visually displays inherited properties and methods:
jsduck ext-4.2.1/src my-project/js –output docs –warnings=-all:ext-4.2.1/src Use code with caution.
(Note: The –warnings=-all:… flag suppresses warning messages generated from checking the base framework files). Option B: Using a Configuration JSON File
For complex projects, passing inline parameters becomes messy. Create a file named jsduck.json in your project root to handle the settings cleanly:
{ “–title”: “My Project API Documentation”, “docs”: [ “my-project/js” ], “–output”: “docs”, “–warnings”: [ “-all:ext-4.2.1/src” ], “–builtin-classes”: true, “–verbose”: true } Use code with caution. Run JSDuck by pointing to your configuration file: jsduck –config jsduck.json Use code with caution. 4. Viewing Your Documentation
After running the command, JSDuck compiles an asset bundle in your specified output directory (docs/). Go to the docs/ folder. Open the index.html file inside any modern web browser.
You will see a highly responsive web interface featuring a class tree navigation menu, live text search, and toggle options to show or hide inherited/protected members. Key JSDuck Tags to Know @class Defines a JavaScript class or namespace. @method Documents an executable function. @param {Type} name Description Documents a method parameter, complete with data type. @return {Type} Description Documents the value and type returned by a function. @property {Type} name Explains a public variable or state. @cfg {Type} name
Specifically denotes a configuration option (vital for ExtJS classes). @private / @protected Limits visibility within the generated UI documentation. Alternative Tool Ecosystem Note
As a historical reference point, JSDuck is an older tool heavily optimized for legacy Sencha/ExtJS class inheritance architectures. If you are writing modern, vanilla modern JavaScript (ES6+), Node.js, or TypeScript applications, you may run into ecosystem friction. In modern workflows, developers usually prefer JSDoc or TypeDoc. If you would like, let me know:
Are you using ExtJS / Sencha, or standard vanilla JavaScript?
Do you need help setting up advanced features like Guides, Videos, or Custom Categories?
JSDuck – Simple JavaScript Duckumentation generator. – GitHub
Leave a Reply