Is there any disadvantage in using jsdoc for library authors?
I haven't used that many npm packages but I see that some don't use any kind of inline documentation at all.
Prisma, zod and better-sqlite3 being one of the few. React uses some but it mainly redirects to official documentation via the @see tag.
Is there a reason some of these libraries don't do inline documentation like lower performance when bundling? Or is it just preference for not cluttering the js files and instead having separate docs
13 Replies
usually it's more question of lazyness than anything
there's no build time impact at all
don't those have a .d.ts file? or already have the types in the .ts file?
.d.ts only gives you types, it doesn't explain what something does (because unless you want to go the java route naming is not enought mosto fthe time)
i know
and you can combine it with jsdoc
Gotcha
By the way is tsdoc the standard for writing these inline docs today? It seems to still have semver at 0.15 something and I checked out the site.
I couldn't see what it fixed from jsdoc besides some tags i didn't see in jsdoc reference
Tho it said it's goal is to be as compatible as it can with jsdoc syntax
there's not really any standard for that... JSDoc is the most well supported across code editors and IDEs but TSDoc has better integration with TS
both are mostly the same in 99% of cases anyway
one notable difference is the way they handle referencing other parts of your code because TS needs to be more specific because of overloads and overrides
So tsDoc is trying to establish a standard for tools that generate docs but it's not a guarantee everything follows it
nah, TSDoc is just the TS team trying to make a tool that works for authoring TS
they don't really try to make it a stendard
Ah okay I read the first line and took it as they meant to make a standard
there's cool integrations for it though, like api-extractor which allows you to bundle you types into a single file and also to turn all your comments into documentation pages
I don't have good experience with those documentation pages... Like with react router v7 but that's probably cause react router team itself was lazy and only put type definitions instead of descriptions
By bundle you mean the index.d.ts things i see
api-reference pages =/= usage doc
pages generated from comments are for technical details, you can't rely on them alone to build your documentation
still need to author usage documentation, tutorials and demos
Gotcha i understand now
Thanks