jsdom VS JSDoc

If you happen to be using React Testing Library in your project, you'll need to keep the jsdom dev dependency installed.

Readability.js requires a DOM object to parse the readable content from a website. That's why we create a DOM object with JSDOM and provide the HTML from the page and its current URL. By the way, the browser may have had to follow HTTP redirects, so the current URL doesn't necessarily have to be the one we provided initially. The parse function of the library returns the following result:

This was the basic usage of JSDOM. If you want to learn more, please check out this documentation.

Web scraping, while immensely useful, often requires developers to navigate a sea of tools and libraries, each with its own quirks and intricacies. Whether it's JSDOM, Cheerio, Playwright, or even just plain old vanilla JS in the DevTools console, moving between these platforms can be a challenge.

React testing library uses jsdom (or others like happy-dom) under the hood to emulate the browser environment and enable testing of different properties. but it doesn't render the component in an actual browser meaning the styles can't be computed and the returned computed style is just an object with the correct keys but empty strings as values.

Note: In order to use the library jsdom to scrape the HTML response we need to avoid the @import statements in the CSS.

The code uses jSDom to render the app but I was wondering if it's possible to run the app without the UI to be able to use a library like that to generate the string from react element.

JSDOM as the DOM environment for running our tests

I wholeheartedly agree. At most, I introduce JSDoc[1] to newer developers as standardising how parameters and whatnot are commented at least gets you better documentation and _some_ safety without adding any TS knowledge overhead.

[1] https://jsdoc.app/

This is where JSDoc comes to save the day.

The best way to do this, of course, is with JSDoc. But something I always found awkward about jsdoc is defining the object types in the same file. So, after a lot of reading, I found a way to combine JSDoc with declaration type files from Typescript. Let me give you an example:

There is a lot of specific symbols presented on the JSDOC specification that can be found here: https://jsdoc.app

JSDoc is a specification for the comment format in JavaScript. This specification allows developers to describe the structure of their code, data types, function parameters, and much more using special comments. These comments can then be transformed into documentation using appropriate tools.

Working with new features, frameworks, and tools, the experience of reading documentation is a critical part of it. I have been lucky to work with projects that feature really easy to read documentation such as USWDS and Bun, but I've also had the misfortune to work with pretty terrible documentation like JSDoc. The JSDoc documentation lacks a search field which makes searching for specific items an ordeal and also does not cover many hidden use cases. It provides less than the bare minimum for what it needs to do - a lot of the time I am forced to rely on external user documentation elsewhere to use JSDoc effectively. That was why I was drawn to the search field in particular in Docusaurus.

The Svelte team followed suit but motivated by the maintainer's developer experience as they migrated the project away from TypeScript in favor of plain JSDoc comments for type annotations instead.

Even more relevant, tools like Javadoc, JSDoc, Doxygen, etc. read comments in a specific format to generate documentation. These comments do not affect readability. On the contrary, Javadocs are great for explaining how to use these entities. Combined with tools like my dear Doctest, we even get guarantees of accuracy and correctness!

Document types with JSDoc annotations

📚 JSDoc for documentation and jsdoc-to-markdown to create docs as markdown files