bevy

bevy copied to clipboard

How can Bevy's documentation be improved?

I've been looking over the documentation a couple of times, thinking that a specific part is inconsistently or at least unusually written.

However, often times the content is still right and I'm not sure if this should or shouldn't be corrected. I'm fully aware that to many rules would only scare people away therefore I suggest to only recommend them instead of strictly enforcing them.

Some example points out of my head:

• Should a link always point to the doc? Most links are pointed to the source code here
• Should doc comments always end with a dot(.)?
• Are headlines always plural (e.g. # Examples but only listing one example)

Also a weird thing that I noticed, is that the winit links here aren't working in the docs but do work in my editor

Should a link always point to the doc? Most links are pointed to the source code here

This seems like a bug / collision in the Transform docs. Only the entry under the "examples" heading should be linking off to source code.

This seems like a bug / collision in the Transform docs

good to know. I'll open a pr later

I'm happy to extend the guidance, but things that can't be enforced automatically shouldn't be turned into rules unless they're extremely intuitive :)

Should doc comments always end with a dot(.)?

For this one, I think it should be enforced in review for sentences to always end with a dot: it's straightforward to do so, and it follow the style of the doc comments in the Rust std. Currently both styles are used in the Bevy doc.

Ideally we could lint for that rather than dealing with it in review.

Would some kind of simple regex-based check in CI do the trick? I don't think this would necessarily fit as a clippy lint, and I checked some code spelling tools but they don't seem to handle that.

Yeah, something along those lines would work fine. Obviously you'd want to have a check for "any punctuation". Ideally the CI check only runs on modified files (and we do a full pass to fix up everything in one big but trivial PR at the start). I do meaningfully prefer this style, but enforcing it in reviews is tedious for both reviewers and authors.