DEV Community

Cover image for Document your Javascript code with JSDoc

Document your Javascript code with JSDoc

Paula Santamaría on August 19, 2019

Introduction In this post I'll try to cover everything you need to know to get started with JSDoc. I'll also share with you some other c...
Collapse
 
ingosteinke profile image
Ingo Steinke, web developer

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.

Collapse
 
paulasantamaria profile image
Paula Santamaría

Totally agree. Glad you enjoyed the post :)

Collapse
 
kevinast profile image
Kevin Bridges

Hi Paula ... nice intro to JSDoc!

You may be interested in this article (bit.ly/docJS) that describes how you can integrate a User's Guide (via GitBook) with your low-level API (using JSDoc).

You can see this in action in the docs of one of my open-source projects: feature-u.js.org/

Collapse
 
paulasantamaria profile image
Paula Santamaría

Thank you Kevin! I've never tried GitBook, but sounds interesting. I'll definitely check out your article, looks like a great way to get the best of both worlds combined!

Collapse
 
yuripredborskiy profile image
Yuri Predborskiy

That swagger jsdoc integration seems interesting - I'm in the process of updating swagger doc file and it is rather inconvenient to do it "by hand" by checking the code every time.

Thanks for info on vs code, I'm trying to get off webstorm and that seems like a decent alternative.

Collapse
 
paulasantamaria profile image
Paula Santamaría

Thanks for reading!
I loved the swagger integration too. It’s better than having to write the whole definition manually in separate files. But, to be honest, it’s still pretty tedious... So I'm still looking for better solutions. This one seems interesting too, but I haven't tried it yet.
I've been a huge fan of VSCode for years, its light and minimalist, but also highly customizable. You should definitely try it!

Collapse
 
blessingraolane profile image
Blessing Raolane

Found anything less tedious?

Collapse
 
quantalabs profile image
QLabs

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.

Collapse
 
krishnasaini profile image
krishna-saini

Hi Paula, exporting using jsdoc path/to/my/file.js was not working for me. On digging deep, I found that this works only if you have installed the jsdoc globally. however if you want to run it locally, you need to include the file location before the jsdoc command.
$ ./node_modules/jsdoc/jsdoc.js file.js

I hope it will help someone

Collapse
 
voluntadpear profile image
Guillermo Peralta Scura

You can even make TypeScript type check your JS files based on JSDoc comments: typescriptlang.org/docs/handbook/t...

Collapse
 
paulasantamaria profile image
Paula Santamaría

Oh, nice one! Thank you

Collapse
 
mauroporras profile image
Mauro Porras

Thanks. documentation.js is a very convenient complement to JSDoc.

Collapse
 
paulasantamaria profile image
Paula Santamaría

Seems interesting, thanks!

Collapse
 
adam_cyclones profile image
Adam Crockett 🌀

Markdown is supported in this style of comment I believe

Collapse
 
paulasantamaria profile image
Paula Santamaría

You're absolutely right, thank you! I haven try it yet, but for anyone interested, here's the official doc about how to use markdown in JSDoc. Seems pretty straight forward.

Collapse
 
adam_cyclones profile image
Adam Crockett 🌀 • Edited

Youre welcome, this is how to take your js doc comments to the next level. 😅

There is no config for vscode btw it just works.

Collapse
 
kikeflowers profile image
kikeflowers

Thank you for sharing this information, I already replicated in my node projects.

Collapse
 
khrome83 profile image
Zane Milakovic

Great write up, thank you!

Collapse
 
paulasantamaria profile image
Paula Santamaría

Thanks for reading!

Collapse
 
estebanfloresf profile image
Esteban Flores

As a QA engineer and frontend on my free time this is useful for both worlds 👍🏼

Collapse
 
paulasantamaria profile image
Paula Santamaría

I'm glad!

Collapse
 
ellen_dev profile image
Ellen Macpherson

This is great, thank you! We use jsdocs at work, so this was a great article on how we can use it better.

Collapse
 
paulasantamaria profile image
Paula Santamaría

Glad I could help! JSDoc has been really useful, even when I'm working alone, it helps me realize if a function or method should be improved or refactored.

Collapse
 
cescquintero profile image
Francisco Quintero 🇨🇴

JSDoc is life. Today I realized I never used it by installing it on projects I worked on 😅 just followed the syntax and tags

Collapse
 
paulasantamaria profile image
Paula Santamaría

So I'm not the only one who did that, awesome! 🤣

Collapse
 
miteshkamat27 profile image
Mitesh Kamat

Easy to understand writeup. Thanks !!

Collapse
 
rowanu profile image
rowan

Thanks for this - have wanted to get into inline documentation, but had not seen a nice intro (and the official docs are a bit... Dry).

Collapse
 
paulasantamaria profile image
Paula Santamaría

I'm flattered :D once you start using JSDoc you won't be able to stop, trust me.

Collapse
 
mm0hammadi profile image
Masoomeh Mohammadi

interesting, thanks