/    Sign up×
Community /Pin to ProfileBookmark

HTML documentation generator for JavaScript

Copy linkTweet thisAlerts:
Feb 21.2023

Hello,

I am writing a codebase in JavaScript. A language that has been standardized by the ECMA. JavaScript that can be run (in a browser, for example). Also called ECMAScript I suppose.

I think it’s important to document all the functions and classes and such in the code base. Are there any commands or utilities that generate a static HTML site based on comments in the source files, similar to the Java and Python and PHP worlds? Ideally one that supports typing information.

What I’ve tried:

  • JSDoc: it just clumps all the functions and classes into a section called “Global”. Not pretty and not useful, as things with the same name get merged together. I know that the `module` tag exists, but it’s redundant as I’ve already declared my modules according to ECMA and duplication is bad. Maybe there is a JSDoc plugin I don’t know about that renders ES modules usefully?
  • ESDoc: automatically detects and works well with modules so that’s a big plus, but isn’t being maintained and also doesn’t support JSDoc import() statements. I could use JavaScript import statements instead, but that code adds needless execution at runtime, and also forces me to make stub functions or classes that can conflict with existing types.
  • Deno docland: looks really pretty and works great with modules, but isn’t a static site generator and using wget to convert it to one doesn’t seem to work well.

Isn’t there any static site documentation generator for JavaScript-JavaScript?

Thank you!

to post a comment
JavaScript

2 Comments(s) ↴

Copy linkTweet thisAlerts:
@cmswebsiteservicessMar 02.2023 — Yes, there are several static site documentation generators for JavaScript that can be used to generate documentation for JavaScript projects. Some of the popular ones include:

JSDoc - JSDoc is a tool that parses JavaScript code to generate API documentation in HTML format. It uses special comment tags to extract information about functions, methods, and other components of a JavaScript project.

YUIDoc - YUIDoc is a documentation tool that is specifically designed for JavaScript projects. It generates API documentation in HTML format and supports a wide range of JavaScript frameworks and libraries.

Docco - Docco is a tool that generates documentation for JavaScript projects in the form of annotated source code. It allows developers to include comments and explanations alongside their code, making it easier to understand and maintain.

ESDoc - ESDoc is a documentation generator that supports JavaScript, TypeScript, and JSX. It generates API documentation in HTML format and supports a wide range of documentation tags.

Docusaurus - Docusaurus is a static site generator that is designed specifically for creating documentation sites. It uses React for the frontend and supports Markdown and MDX for content.

These tools make it easy to generate comprehensive and accurate documentation for JavaScript projects, helping developers to improve the readability and maintainability of their code.
Copy linkTweet thisAlerts:
@Lexxy_FoxApr 28.2023 — I can't get any of the tools I've tried to work...

* JSDoc: just spams "ERROR: Unable to parse a tag's type expression for source file ..." on any reasonably complex {} expression, especially function/callback types. Couldn't figure out how to convert some of the more complex function types to @typedefs.
* YUIDoc: Can't locate any types ("Missing item type"). Generates an index without any classes or modules listed. Does generate a single html page for each javascript module, but its simply the source code with syntax highlighting, and the checkboxes seem to do nothing. Not useful.
* Docco Next: Actually generates HTML files, but it's really ugly. Again, syntax highlighed source code, but the code is broken up into sections with each section having a useless header such as "@ts-ignore:". At the top of each file is a massive list of links, one to each file in the tree even if it's not a JavaScript file.
* ESDoc: Doesn't support current (2023-04-01) JavaScript syntax (the "??" operator). Also hasn't been updated in years. Their web tool (https://doc.esdoc.org/-/generate.html) doesn't work ("This is invalid git url. Valid format is ..."). Also gives the error "SyntaxError: Invalid regular expression: /[~]import("./types$/: Unterminated group".
* Deno docland: Isn't a static site generator. Also doesn't work with const expressions.
* Docusaurus: Well this is just a DIY website generator. Seems quite easy to pick up, and pretty capable too. I suppose this is what we'll have to use.

Ultimately settled on Docusaurus for now, but thought I'd leave my findings here for other developers. Really dissappointed that there doesn't seem to be any tool that generates static HTML pages from JavaScript comments, like there is for Python, Java, and PHP. I suppose I'll have to write it myself sometime.
×

Success!

Help @MichaelGarrett spread the word by sharing this article on Twitter...

Tweet This
Sign in
Forgot password?
Sign in with TwitchSign in with GithubCreate Account
about: ({
version: 0.1.9 — BETA 4.26,
whats_new: community page,
up_next: more Davinci•003 tasks,
coming_soon: events calendar,
social: @webDeveloperHQ
});

legal: ({
terms: of use,
privacy: policy
});
changelog: (
version: 0.1.9,
notes: added community page

version: 0.1.8,
notes: added Davinci•003

version: 0.1.7,
notes: upvote answers to bounties

version: 0.1.6,
notes: article editor refresh
)...
recent_tips: (
tipper: @Yussuf4331,
tipped: article
amount: 1000 SATS,

tipper: @darkwebsites540,
tipped: article
amount: 10 SATS,

tipper: @Samric24,
tipped: article
amount: 1000 SATS,
)...