Add rustdoc comments to all public APIs

oxc-project / oxc

⚓ A collection of JavaScript tools written in Rust.

https://oxc.rs

MIT License

12.33k stars 450 forks source link

Add rustdoc comments to all public APIs #5870

Closed DonIsaac closed 3 weeks ago

DonIsaac commented 1 month ago

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

[x] 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
[x] #5865

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

overlookmotel commented 1 month ago

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 commented 1 month ago

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

overlookmotel commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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

Boshen commented 3 weeks ago

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

overlookmotel commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

Transferred to https://github.com/oxc-project/backlog/issues/130