This PR is part of the issue #3492.
# Objective
- Add and update the bevy_tasks documentation to achieve a 100% documentation coverage (sans `prelude` module)
- Add the #![warn(missing_docs)] lint to keep the documentation coverage for the future.
## Solution
- Add and update the bevy_math documentation.
- Add the #![warn(missing_docs)] lint.
- Added doctest wherever there should be in the missing docs.
Closes#3497.
I added the rust API guidelines (https://rust-lang.github.io/api-guidelines/about.html) to the `CONTRIBUTING.md` file.
## Note
As noted in #3497 we should note any areas where we deliberately disagree as they arise. If we start adding these areas it might be a good idea to remove the mention of the `API guidelines` in the `CONTRIBUTING.md` file and move it to the `engine_style_guide.md`. That way we still have the connection between the `CONTRIBUTING.md` and the `API guidelines`, but we have more "space" to work with and can go into more detail about what we agree and disagree on.
For now I would leave it this way, because it's one less click to get to the guidelines.
Co-authored-by: KDecay <KDecayMusic@protonmail.com>
# Objective
Emitting compile errors produces cleaner messages than panicking in a proc-macro.
## Solution
- Replace match-with-panic code with call to new `bevy_macro_utils::get_named_struct_fields` function
- Replace one use of match-with-panic for enums with inline match
_Aside:_ I'm also the maintainer of [`darling`](https://docs.rs/darling), a crate which provides a serde-like API for parsing macro inputs. I avoided using it here because it seemed like overkill, but if there are plans to add lots more attributes/macros then that might be a good way of offloading macro error handling.
# Objective
- On Safari mobile, calling `winit_window.set_cursor_grab(true)` fails as the API is not implemented (as there is no cursor on Safari mobile, the api doesn't make sense there). I don't know about other mobile browsers
```
[Error] Unhandled Promise Rejection: TypeError: getObject(arg0).exitPointerLock is not a function. (In 'getObject(arg0).exitPointerLock()', 'getObject(arg0).exitPointerLock' is undefined)
(anonymous function) (rect.js:1089)
wasm-stub
<?>.wasm-function[web_sys::features::gen_Document::Document::exit_pointer_lock::h20ffc49be163fc45]
<?>.wasm-function[winit::platform_impl::platform::backend::canvas::Canvas::set_cursor_grab::h6a9472cf55263e98]
<?>.wasm-function[bevy_winit::winit_windows::WinitWindows::create_window::h9db5b3cbb24347c5]
<?>.wasm-function[<bevy_winit::WinitPlugin as bevy_app::plugin::Plugin>::build::ha4a7c046b80c4280]
<?>.wasm-function[bevy_app::plugin_group::PluginGroupBuilder::finish::h0e5bc78f71c37b2f]
<?>.wasm-function[rect::main::h899852fd17f2d489]
<?>.wasm-function[std::sys_common::backtrace::__rust_begin_short_backtrace::hfe38f282e8dda96b]
<?>.wasm-function[std::rt::lang_start::{{closure}}::hc2f3b555ffc58618]
<?>.wasm-function[std::rt::lang_start_internal::ha901ae30d88554f2]
<?>.wasm-function[main]
<?>.wasm-function[]
wasm-stub
21261
(anonymous function) (rect.js:1664)
asyncFunctionResume
(anonymous function)
promiseReactionJobWithoutPromise
promiseReactionJob
```
## Solution
- Do not call the api to release cursor grab on window creation, as the cursor is not grabbed anyway at this point
# Objective
- Fix incorrect iterator usage in WriteStd430 impl for [T]
- The first item was being written twice. This is correct in the WriteStd140 impl for [T].
## Solution
- See the code.
Documentation added to:
- `App::add_sub_app` (
- `App::update` (mentions that sub apps are updated here)
### Future work
- An example for `add_sub_app` would be good, but I wasn't able to come up with a simple one.
- Since `SubApp` is private, maybe the concept of sub applications could be introduced in the `App` struct-level documentation.
This adds documentation for:
- The trait methods of `Reflect` and its subtraits
- The `partial_eq` and `apply` functions for `Map` et al.
- `DynamicList` and `DynamicMap`
- `TypeRegistry` and related types & traits
- `GetPath`, including an explanation of path string syntax
among other things.
Still to be documented are the various macros and `bevy_reflect::serde`.
adds an example using UI for something more related to a game than the current UI examples.
Example with a game menu:
* new game - will display settings for 5 seconds before returning to menu
* preferences - can modify the settings, with two sub menus
* quit - will quit the game
I wanted a more complex UI example before starting the UI rewrite to have ground for comparison
Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
# Objective
bevy_transform needed documentation and warn(missing_docs) as requested by #3492
## Solution
warn(missing_docs) was activated and documentation was added to cover the crate
Co-authored-by: Troels Jessen <kairyuka@gmail.com>
# Objective
- Fixes#3616
## Solution
- As described in the issue, documentation for `iter_manual` was copied from `iter_combinations` and did not reflect the behavior of the method. I've pulled some information from #2351 to create a more accurate description.
# Objective
- Removes warning about accidently inserting bundles with `EntityCommands::insert`, but since a component now needs to implement `Component` it is unnecessary.
Super tiny thing. Found this while reviewing #3479.
# Objective
- Simplify code
- Fix the link in the doc comment
## Solution
- Import a single item :)
Co-authored-by: Pascal Hertleif <pascal@technocreatives.com>
# Objective
The description of NixOS dependencies is extremely long and spends entire paragraphs just for simple line changes.
With this PR it should be much simpler.
## Solution
- Linking Vulkan in `build.rs` is less effective than adding it in LD_LIBRARY_PATH, so I removed the former (related to #1992);
- I put a simple comment explaining the line in the list of dependencies, instead of making entire paragraphs;
- Clang is not in an absolute path in `.cargo/config_fast_builds` anymore, so that there is no need to specify it in `docs/linux_dependencies.md` (didn't test if this breaks other distros, though I doubt it. Also, maybe it could also be done on Darwin for consistency?);
- Also added optional wayland dependencies.
A few notes:
- The x11 libraries will be linked only during the compilation phase. This means that if you use the `x11` feature without these libraries in the environment (for example because you forget to enter the nix shell before compiling), the program will still compile successfully but won't run. You'll have to `cargo clean` and recompile with the x11 libraries in the environment. I don't know if this is important enough to be added to the documentation, but it's not specified anywhere, though I don't think it's specific to NixOS;
- The wayland dependencies need to be put in LD_LIBRARY_PATH only in certain conditions (IIRC, only if using the `dynamic` feature) and the text doesn't specify it. Because putting them there doesn't increase the number of dependencies (they are already in buildInputs) or alter the performance, I doubt anyone will care;
- Should I comment out what isn't needed by default?
- ~I removed `cargo` from buildInputs. Ignoring the fact that it should be in nativeBuildInputs, having it in `shell.nix` allows to use stable Rust in case it's not in the system environment, but maybe the user wanted to use the version that was already in the system environment and will be caught by surprise. In my opinion, if someone is looking at a Bevy's documentation on NixOS, that user will either have Rust already in the system environment (eg. via rustup) or is capable to add the toolchain they want on shell.nix by themselves. This isn't exactly the place to explain how this works.~ ~EDIT: I replaced `cargo` with Rust from the [Oxalica overlay](https://github.com/oxalica/rust-overlay) in order to have the latest nightly.~ EDIT: Removed `cargo` from dependencies. See comments for details.
# Objective
CI should check for missing backticks in doc comments.
Fixes#3435
## Solution
`clippy` has a lint for this: `doc_markdown`. This enables that lint in the CI script.
Of course, enabling this lint in CI causes a bunch of lint errors, so I've gone through and fixed all of them. This was a huge edit that touched a ton of files, so I split the PR up by crate.
When all of the following are merged, the CI should pass and this can be merged.
+ [x] #3467
+ [x] #3468
+ [x] #3470
+ [x] #3469
+ [x] #3471
+ [x] #3472
+ [x] #3473
+ [x] #3474
+ [x] #3475
+ [x] #3476
+ [x] #3477
+ [x] #3478
+ [x] #3479
+ [x] #3480
+ [x] #3481
+ [x] #3482
+ [x] #3483
+ [x] #3484
+ [x] #3485
+ [x] #3486
#3457 adds the `doc_markdown` clippy lint, which checks doc comments to make sure code identifiers are escaped with backticks. This causes a lot of lint errors, so this is one of a number of PR's that will fix those lint errors one crate at a time.
This PR fixes lints in the `bevy_render` crate.
# Objective
This PR extends the `Events` documentation by:
- informing user about the possible race condition
- explicitly explaining the unusual double buffer implementation
Fixes#3305
Co-authored-by: MiniaczQ <jakub.motyka.2000@gmail.com>
Co-authored-by: MiniaczQ <MiniaczQ@gmail.com>
# Objective
These traits are undocumented on `main`.
## Solution
Now they have docs! Included are examples for each trait and their corresponding `GetTypeField` trait. The docs also mention that `#[derive(Reflect)]` will automatically derive the correct subtrait on structs and tuple structs.
# Objective
In this PR I added the ability to opt-out graphical backends. Closes#3155.
## Solution
I turned backends into `Option` ~~and removed panicking sub app API to force users handle the error (was suggested by `@cart`)~~.
# Objective
The current 2d rendering is specialized to render sprites, we need a generic way to render 2d items, using meshes and materials like we have for 3d.
## Solution
I cloned a good part of `bevy_pbr` into `bevy_sprite/src/mesh2d`, removed lighting and pbr itself, adapted it to 2d rendering, added a `ColorMaterial`, and modified the sprite rendering to break batches around 2d meshes.
~~The PR is a bit crude; I tried to change as little as I could in both the parts copied from 3d and the current sprite rendering to make reviewing easier. In the future, I expect we could make the sprite rendering a normal 2d material, cleanly integrated with the rest.~~ _edit: see <https://github.com/bevyengine/bevy/pull/3460#issuecomment-1003605194>_
## Remaining work
- ~~don't require mesh normals~~ _out of scope_
- ~~add an example~~ _done_
- support 2d meshes & materials in the UI?
- bikeshed names (I didn't think hard about naming, please check if it's fine)
## Remaining questions
- ~~should we add a depth buffer to 2d now that there are 2d meshes?~~ _let's revisit that when we have an opaque render phase_
- ~~should we add MSAA support to the sprites, or remove it from the 2d meshes?~~ _I added MSAA to sprites since it's really needed for 2d meshes_
- ~~how to customize vertex attributes?~~ _#3120_
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
# Objective
Updated the docs for bevy_ui as requested by #3492
## Solution
I have documented the parts I understand. anchors.rs is not in use and should be removed, thus I haven't documented that, and some of the more renderer-heavy code is beyond me and needs input from either cart or someone familiar with bevy rendering
Co-authored-by: Troels Jessen <kairyuka@gmail.com>
# Objective
- Using plain exponential depth slicing for perspective projection cameras results in unnecessarily many slices very close together close to the camera. If the camera is then moved close to a collection of point lights, they will likely exhaust the available uniform buffer space for the lists of which lights affect which clusters.
## Solution
- A simple solution to this is to use a different near plane value for the depth slicing and set it to where the first slice's far plane should be. The default value is 5 and works well. This results in the configured number of depth slices, maintains the exponential slicing beyond the initial slice, and no slices are too small such that they cause problems that are sensitive to the view position.
# Objective
- Fix the case mentioned in https://github.com/bevyengine/bevy/pull/2725#issuecomment-1007014024.
- On a machine with 4 cores, so 1 thread for assets, loading a gltf with only one textures hangs all asset loading
## Solution
- Do not use the task pool when there is only one texture to load
Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
# Objective
- More colours
## Solution
- Various changes
- Would have a video here, but don't have an easy way to record one before I go to sleep
- I intend to additionally change the distribution of the satellites, to be more uniform in space.
#3457 adds the `doc_markdown` clippy lint, which checks doc comments to make sure code identifiers are escaped with backticks. This causes a lot of lint errors, so this is one of a number of PR's that will fix those lint errors one crate at a time.
This PR fixes lints in the `bevy_ecs` crate.
# Objective
Part of #3492
- Complete inline documentation of `bevy_audio`
## Solution
- Added inline documentation to all public parts of `bevy_audio`
- Added a few inline examples at important places
- Some renaming for clarity (e.g. `AudioLoader` and generics)
- added `#![warn(missing_docs)]` and `#![forbid(unsafe_code)]` to `bevy_audio`
I also tried adding support for the other vorbis file endings `.oga` and `.spx` to the `AudioLoader` (see `file endings` at https://tools.ietf.org/html/rfc5334#section-10.3), but the `rodio` decoder does not seem to support those.
#3457 adds the `doc_markdown` clippy lint, which checks doc comments to make sure code identifiers are escaped with backticks. This causes a lot of lint errors, so this is one of a number of PR's that will fix those lint errors one crate at a time.
This PR fixes lints in the `bevy_ui` crate.
#3457 adds the `doc_markdown` clippy lint, which checks doc comments to make sure code identifiers are escaped with backticks. This causes a lot of lint errors, so this is one of a number of PR's that will fix those lint errors one crate at a time.
This PR fixes lints in the `bevy_text` crate.
# Objective
- Fixes#1920.
- Users often want to know how to get the values of removed components (#1655).
- Stand-alone `bevy_ecs` behavior is very unintuitive, as `World::clear_trackers()` must be manually called.
- Fixes#2999 by extending the existing test (thanks @hymm for pointing me to it) to be clearer and check for component removal as well.
## Solution
- Better docs!
- Better tests!
# Objective
- Load names of lights from gltf
## Solution
- Load names of lights from gltf
Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
# Objective
- Allow the user to specify the priority when configuring wgpu features/limits and by default use the maximum capabilities of the chosen adapter.
## Solution
- Add a `WgpuOptionsPriority` enum with `Compatibility`, `Functionality` and `WebGL2` options.
- Add a `priority: WgpuOptionsPriority` member to `WgpuOptions`.
- When initialising the renderer, if `WgpuOptions::priority == WgpuOptionsPriority::Functionality`, query the adapter for the available features and limits, use them when creating a device, and update `WgpuOptions` with those values. If `Compatibility` use the behaviour as before this PR. If `WebGL2` then use the WebGL2 downlevel limits as used when when building for wasm, for convenience of testing WebGL2 limits without having to build for wasm.
- Add an environment variable `WGPU_OPTIONS_PRIO` that takes `compatibility`, `functionality`, `webgl2`.
- Default to `WgpuOptionsPriority::Functionality`.
- Insert updated `WgpuOptions` into render app world as well. This is useful for applying the limits when rendering, such as limiting the directional light shadow map texture to 2048x2048 when using WebGL2 downlevel limits but not on wasm.
- Reduced `draw_state` logs from `debug` to `trace` and added `debug` level logs for the wgpu features and limits. Use `RUST_LOG=bevy_render=debug` to see the output.
# Objective
- For a plugin, I would like to enable `bevy_ui` without adding the complete `render` feature
## Solution
- Add a feature for `bevy_ui`
Co-authored-by: François <8672791+mockersf@users.noreply.github.com>
Modifies the code emitted by `derive_label` to use fully-qualified type
names (e.g. `std::boxed::Box` instead of `Box`).
# Objective
- Using unqualified types here causes errors when the proc macro is used in contexts that locally define types with conflicting names (e.g. a local definition of `Box`).
## Solution
- Fully qualify standard types emitted by the proc macro code.
