YARD VS swc

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).

First, we switched the default compiler for new projects from Babel to SWC (Speedy Web Compiler). SWC is dramatically faster than Babel and requires zero configuration. We’ll continue to support Babel in any project currently using it.

SWC

As the reference explains “**SWC** (Speedy Web Compiler) is an extensible Rust-based platform that can be used for both compilation and bundling. Using SWC with Nest CLI is a great and simple way to significantly speed up your development process.”

This is specifically about breaking the myth that performing expensive self-contained operations (e.g, parsing GraphQL) in a native extension (C, Rust, etc.) is always faster than the interpreted language.

The JS ecosystem has the same problem, people think rewriting everything in Rust will be a magic fix. In practice, there's always the problem highlighted in the post (transitioning is expensive, causes optimization bailouts), as well as the cost of actually getting the results back into Node-land. This is why SWC abandoned the JS API for writing plugins - constantly bouncing back and forth while traversing AST nodes was even slower than Babel (e.g https://github.com/swc-project/swc/issues/1392#issuecomment-...)

Why Speedy Web Compiler ?

FTA is a TypeScript static analysis tool built on the speedy foundations of swc. FTA is fast; capable of analyzing more than 150 files per second on typical hardware, it offers a powerful addition to your code quality toolkit.

Very cool! I'm curious, is this intended for dev tooling?

For example, I could see this (or something similar) being useful as the engine for a typescript language server that would be faster than the standard one

But if it's not aimed at 1:1 with tsc, would it be intended more for something like swc[1]?

Or what would you expect people to use this for, besides just being a cool project to learn from?

[1] https://github.com/swc-project/swc

This is... good news, but I still cannot fathom using the default Typescript compiler for regular development. Seriously, leave the type-checking to your IDE and CICD chain, and switch to using tsx (https://www.npmjs.com/package/tsx) or swc (https://swc.rs/) and you will _immediately_ notice the difference in speed and productivity.