YARD VS parcel

JSDOC is a predefined method of documenting code for javascript ecosystem created in 1999 that works similar to libraries for other languages such as: Javadoc for java, YARD for ruby, etc..

In addition to project documentation, you've included a lot of code comments. You could adopt a standardized format and use it to generate API documentation. RDoc and YARD are two options. If I were reviewing this code at work, I would probably ask you to remove comments that explain what, not why.

I still just document everything using YARD and focus on designing really obvious Object Models and of course write tests. I have tried using sord to convert my YARD type annotations to RBS or RBI, but you still have to fill in missing bits, then use steep and somehow load in RBS/RBI files for other gems and stdlib, and it's just an uphill battle since Ruby is dynamically typed by default. Obviously Dynamic Typing lends itself more to Dynamic Languages, where you can call an arbitrary method and let the language VM figure it out at runtime. Static or Strong Typing lends itself better to compiled languages where everything needs to be resolved at compile time and converted into object code. If I need to work in a compiled language, then I'll use Crystal, which also supports type inference. TypeScript's type syntax is quite nice, but I tend to avoid writing massive JavaScript code bases where a Type Checker helps catch subtle bugs, and instead prefer sticking to minimal amounts of vanilla JavaScriot in order to keep complexity low and not overwhelm the browser.

I had a dig into the file history, and it looks like we have to go back to 0.7 to find the old tag list. Here we find the info we need to understand the intent of the @option tag:

YARD: http://yardoc.org/

I tend to follow along using the YardDoc comment style. It has many small things I love about it; an example is when yardoc is followed it can be used to generate RBS/Sorbet type files with the sord gem, you can also generate application documents similar to rdoc/sdoc.

That turns out to be a pretty common use case for markdown. Github, for example, renders your README.md is part of a git repo's "home" page. It's also common to have tooling that parses specially formatted comments in your source code and produce a documentation bundle, usually as a web page (ex. RDoc, YARD, JSDoc, etc.).

My first assumption was, that I should be able to generate markdown from the source. Same ruby and rails does now, but only tweaking a couple of parameters to generate .md files instead. YARD is being used for that and it supports any markup rdoc or yard.

I’ve long used the YARD format and chose to use that as my documentation syntax. I suppose I didn’t check with anyone on this decision and slowly started adding documentation. I want to use this post to synthesize my implicit decision and the benefits of using Yard as the documentation format.

That said, YARD is a ruby documentation tool that has a yard graph command you can use to dump a UML graph for your app into a .dot file, which can be used with lots of different graphing tools (usually graphviz but there are a bunch of online tools and open source projects that can visualize them for you).

It runs using Parcel, very simple and easy to setup. The app has 3 files:

Homepage: https://parceljs.org/

In the Changelog Podcast episode referenced above, Dan Abramov alluded to Parcel working on RSC support as well. I couldn’t find much to back up that claim aside from a GitHub issue discussing directives and a social media post by Devon Govett (creator of Parcel), so I can’t say for sure if Parcel is currently a viable option for developing with RSCs.

Parcel 2 emphasizes a zero-configuration approach to bundling web applications. It's a powerful tool that offers a hassle-free developer experience, focusing on simplicity and speed.

Once you build a simple Vite backend integration, try not to complicate Vite's configuration unless you absolutely must. Vite has become one of the most popular bundlers in the frontend space, but it wasn't the first and it certainly won't be the last. In my 7 years of building for the web, I've used Grunt, Gulp, Webpack, esbuild, and Parcel. Snowpack and Rome came-and-went before I ever had a chance to try them. Bun is vying for the spot of The New Hotness in bundling, Rome has been forked into Biome, and Vercel is building a Rust-based Webpack alternative.

Parcel

I’ve tried something similar on the frontend side: I decided to build a UI for Ollama.ai using only HTML, CSS, and JS (Single-Page Application). The goal is to learn something new and have zero runtime dependencies on other projects and NPM modules. Only Node and Parcel.js (https://parceljs.org/) are needed during development for serving files, bundling, etc. The only runtime dependency is a modern browser.

Here's what I have found so far:

- JavaScript (vanilla) is a viable alternative to React.js

Besides Webpack, there are many other popular web bundlers available, such as Parcel, Esbuild, Rollup, and more. They all have their own unique features and strengths, and you should make your decision based on the needs and requirements of your specific project. Please refer to their official websites for details.

In the Node.js ecosystem, bundling is typically handled by third-party tools rather than Node.js itself. Some of the most popular bundlers in the Node.js world include Webpack, Rollup, and Parcel, offering features like code splitting, tree shaking, and hot module replacement.

There are projects attempting to do more things. I've really enjoyed Parcel (https://parceljs.org). But it won't handle things like linting or unit testing, which you may or may not want. Vite is also pretty popular (https://vitejs.dev/), and it has a test runner.

Thing is, most of the problems described in the post aren't related to low-JS front-end libraries like HTMX or alpine. You can write React without a linter, bundler, build tool, unit testing, or linting. But with any of these projects at scale, you start wanting more:

- If you want to write unit tests in JS, you need to choose a test runner (probably Jest or Vitest -- until the built-in node testing module becomes more common).

- If you want linting, you need a linter (probably Eslint). If you want type safety, you need a type checker (probably Typescript).

- If you want to create smaller JS files to ship to production and to automatically handle assets, you need a bundler.

- If you want to use new language features while supporting old browsers, you need polyfills.

- If you want to use all these things together, you need something to bring it together (like Webpack).

So it really depends what you need! You may not need any. But as you can imagine, in many professional projects with multiple developers it's very nice to have unit tests, linting, and type checking :) (And you start caring about end-user performance a lot more, in which case optimizing the shipped bundle is important.)

Take all that, and then compare to a language like Rust, which has most of the "ecosystem stuff" built-in. In Rust, you get the test runner, the linter, dependency manager, type checker, and documentation tool all included. Easy! Thankfully, Rust doesn't have to care about whether users support modern language features (because it compiles down to lower code ahead of time), or whether the binary shipped to the client is optimally organized for downloading immediately over the internet.

It's a problem in JS because A) you have to care about more problems than many other languages since JS needs to load instantly over the wire in a web browser, and B) there is a huge amount of choice and not a lot of standardization in web tools. (And what standardization there is (Node, npm), there are still competitors trying to even further reduce the pain points.)

I think that in ten more years, we'll be in a better place, because there is push back (like this post!) against these problems, which will encourage more tools trying to solve the explosion of tools. Which seems counterintuitive, but these tools were created to solve very real problems. So I see it as a pendulum which has swung too far, but will likely swing back to a more balanced place. And you see that with tools like Vite gaining popularity.