Add rustdoc comments to all public APIs

[DonIsaac]

Good documentation is a critical part of promoting adoption from other projects. If users cannot understand how to use our tools, odds are they wont. We should document as much of our public API as possible. At the very least, all mostly-stable APIs should have examples and descriptions on how to use them.

We have a lot of great examples, but many options and return structures are missing descriptions. Plenty of business logic is also missing descriptions.

Crates

These are, in my opinion, the crates that are most important to document right now

• oxc (doesn't receive module docs from its re-exports, README is missing)
• oxc_parser (mostly documented)
• oxc_ast (partially documented)
• oxc_transformer
• oxc_codegen
• oxc_isolated_declarations
• oxc_semantic
• oxc_span
• docs(diagnostics): fully document oxc_diagnostics #5865

Basically, if it's used anywhere from reading a file -> parsing -> transforming -> printing, then it is a high-priority candidate.

[overlookmotel]

Just to add, documentation on internal APIs is also helpful - not just for new contributors, but also for the core team. I often find myself a bit lost in areas of codebase I've not been in for a while. Obviously, public API is higher priority, though.

[DonIsaac]

I'm not familiar enough with the transformer to tackle this. Is someone else willing to handle it?

[overlookmotel]

I am currently working through the transformer fixing bugs and refactoring. I'll do my best to also add comments as I go. FYI we've adopted a "style guide" for writing transforms which includes requirement to comment well.

[DonIsaac]

I'm not familiar enough with the transformer to tackle this. Is someone else willing to handle it?

I'm also not super familiar with codegen or ID, would love support on these

[Boshen]

It seems like we can add missing_docs = "warn" one by one to these crates.

[Boshen]

Close as stale for house keeping. Nobody likes writing documentations so I don't think we'll get any help 😅

[overlookmotel]

Moving to backlog, as I think this is something that we should tackle at some point - I believe it is important, for the reasons that Don gives at the top.

[overlookmotel]

Transferring to backlog repo did not work. Github seems to have some kind of race condition. Going to leave this for a few hours for it to settle down and then try again.

[overlookmotel]

Transferred to oxc-project/backlog#130