Guidelines for the crate level documentation : fixing the inconsistencies

[tguichaoua]

The problem

There is not guidelines on how to make the docs for the internal crates.
#3492 is completed little by little by many people leading to a lot of inconsistency in the documentations.

Here's an example if you search for "prelude" on docs.rs :

If we look at the first sentence of the docs they generally mention Bevy, but sometimes it's called "the Bevy game engine" and other times "the game engine Bevy" or just "Bevy".

bevy_math

//! Provides math types and functionality for the Bevy game engine.

bevy_animation

//! Animation for the game engine Bevy

bevy_gizmos

//! This crate adds an immediate mode drawing api to Bevy for visual debugging.

bevy_app

//! This crate is about everything concerning the highest-level, application layer of a Bevy app.

bevy_winit didn't even mention Bevy (also, it's missing a full stop).

//! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`]

bevy_time includes a README

#![doc = include_str!("../README.md")]

Also crate attributes are placed before the docs and sometime after.

#![allow(clippy::type_complexity)]
#![warn(missing_docs)]

Roadmap

1. Have a discussion to establish rules for documentation and create a guidelines file in the .github/contributing directory.
2. Open a PR to apply the rules on the existing docs.
3. Use the guidelines for the future contributions to #3492.

Points to discuss

• The docs on prelude modules
  • Always the same sentence (e.g. Commonly used items)?
  • Use the crate's name (e.g The Bevy Time prelude)? Should the crate's name be CamelCase or snake_case?
• Crates attributes before or after the crate docs? (I open a discussion on the rust forum with a poll and another one on reddit)
• Should Bevy be mentionned ? If yes, just Bevy, the Bevy game engine, the game engine Bevy or anything else ? Does it also include a link to the Bevy website?

[tguichaoua]

My point of view on the question :

• When reading the docs of the main crate all prelude modules are mixed up, so their docs should mention the name of their crate. e.g. The Bevy Time prelude.

• I prefer put the crates attributes before the docs. But I haven't a strong opinion on this one. This is why I open a poll on the rust forum and on reddit.

If the crate is an extension of the game engine (e.g. bevy_time, bevy_math, etc.) the docs should be something like :

//! Add <list of functionality> functionality to the [Bevy game engine].
//!
//! <more docs here, optional>
//!
//! [Bevy game engine]: https://bevyengine.org/

If the crate adapts an external crate for Bevy (e.g. bevy_winit, bevy_gilrs, etc.) the docs should be something like :

//! Integrates the [`external`] crate to the [Bevy game engine].
//!
//! <more docs here, optional>
//!
//! [`external`]: <the docs.rs url to the external crate>
//! [Bevy game engine]: https://bevyengine.org/

Those rules didn't apply for standalone crates like bevy_reflect.

[alice-i-cecile]

I'm fine to merge consistency PRs (ideally one flavor of fix at a time), but unless we can automatically enforce it we shouldn't make it a "rule".

[alice-i-cecile]

Always the same sentence (e.g. Commonly used items)?

Sure, I'm happy with that.

Use the crate's name (e.g The Bevy Time prelude)? Should the crate's name be CamelCase or snake_case?

snake_case, with code formatting.

Crates attributes before or after the crate docs? (I open a discussion on the rust forum with a poll and another one on reddit)

Mild preference to after but I don't care.

Should Bevy be mentionned ? If yes, just Bevy, the Bevy game engine, the game engine Bevy or anything else ? Does it also include a link to the Bevy website?

Yes, I think just "the Bevy game engine" is nice.

[alice-i-cecile]

This belongs in the Contributing Guide. Transferring the issue.