bevyengine / bevyengine/bevy-website

Guidelines for the crate level documentation : fixing the inconsistencies

Open
#1,944 4 comments 0 reactions 0 assignees View on GitHub
A-Contributing-Guide C-Content C-Docs S-Ready-For-Implementation
Dominant language
JavaScript
Stars
249
Forks
450
Avg merge
16h 20m
Merged PRs (30d)
6

Description

## 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 :

![image](https://github.com/bevyengine/bevy-website/assets/33934311/ab7bd8d4-8a8a-46a6-9835-c8eca5ee23ad)

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`
```rust
//! Provides math types and functionality for the Bevy game engine.
```

`bevy_animation`
```rust
//! Animation for the game engine Bevy
```

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

`bevy_app`
```rust
//! 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).
```rust
//! `bevy_winit` provides utilities to handle window creation and the eventloop through [`winit`]
```

`bevy_time` includes a README
```rust
#![doc = include_str!("../README.md")]
```

Also crate attributes are placed before the docs and sometime after.
```rust
#![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](https://users.rust-lang.org/t/crate-attributes-before-or-after-the-crate-docs/98645?u=tguichaoua) and [another one on reddit](https://www.reddit.com/r/rust/comments/15vpqrs/crate_attributes_before_or_after_the_docs/?utm_source=share&utm_medium=web2x&context=3))
- 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?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.