[Merged by Bors] - docs: Full documentation for bevy_asset #3536

manokara · 2022-01-03T02:52:26Z

Objective

This PR aims to document the bevy_asset crate to complete coverage, while also trying to improve some bits of UX.

Progress

Coverage: 100%

Migration Guide

Rename FileAssetIo::get_root_path uses to FileAssetIo::get_base_path

FileAssetIo::root_path() is a getter for the root_path field, while FileAssetIo::get_root_path returned the parent directory of the asset root path, which was the executable's directory unless CARGO_MANIFEST_DIR was set. This change solves the ambiguity between the two methods.

mockersf · 2022-01-03T09:28:56Z

#3348 is also adding some docs in bevy_assets

manokara · 2022-01-03T12:14:22Z

Oh, and it's more detailed than mine! I just focused on giving them short summaries for the coverage. We should merge that one first and I'll rebase my work on top of it.

alice-i-cecile · 2022-01-04T23:37:49Z

Awesome. I'll work on getting #3348 merged now then.

crates/bevy_asset/src/handle.rs

crates/bevy_asset/src/info.rs

manokara · 2022-01-11T19:09:03Z

All is done! Now the PR is up for full review. Everything is documented except for things that are self-expanatory, such as AssetEvent variants. And I think the crate level docs need some work.

There were a few code changes:

Removed SourceMeta for having the Vec<AssetMeta> directly in SourceInfo.
Renamed LoadContext::get_asset_metas to generate_asset_metas.
Renamed Handle::as_weak to cast (see Handle<T>::as_weak() takes a type U which is potentially bad #3522).
Update the handle's type uuid in Handle::cast.

Each one was made as a separate commit, so if they're out of scope for this PR it'll be easy to revert them.

crates/bevy_asset/src/asset_server.rs

crates/bevy_asset/src/assets.rs

crates/bevy_asset/src/diagnostic/asset_count_diagnostics_plugin.rs

crates/bevy_asset/src/filesystem_watcher.rs

alice-i-cecile

These are really solid: detailed and technical but covering how and why you may want to use these.

I have a few nits, and want to chat a bit more about the as_weak vs cast decision.

crates/bevy_asset/src/assets.rs

crates/bevy_asset/src/diagnostic/mod.rs

crates/bevy_asset/src/handle.rs

manokara · 2022-01-12T23:19:56Z

I was thinking of renaming AssetStage::LoadAssets as well, because it is not quite what that stage does as the docstring says. UpdateAssets?

alice-i-cecile · 2022-01-13T00:52:49Z

I was thinking of renaming AssetStage::LoadAssets as well, because it is not quite what that stage does as the docstring says. UpdateAssets?

Yes please.

alice-i-cecile · 2022-01-13T01:53:18Z

Migration Guide:

Renamed AssetStage::LoadAssets to UpdateAssets
Renamed Handle::as_weak to Handle::cast

manokara · 2022-07-11T13:29:41Z

All done! I reverted the breaking changes as @alice-i-cecile suggested, but kept the get_root_path() one because it fixes the ambiguity with root_path(). I will make a separate PR for the others when this one is merged.

alice-i-cecile · 2022-07-11T13:42:29Z

@bevyengine/docs-team I would really like to land this for 0.8.

crates/bevy_asset/src/asset_server.rs

crates/bevy_asset/src/handle.rs

crates/bevy_asset/src/lib.rs

crates/bevy_asset/src/asset_server.rs

IceSentry

I didn't review everything with a lot of details but it all seemed pretty good.

alice-i-cecile · 2022-07-12T15:43:52Z

Did a final review pass, everything checks out :) Thanks y'all!

bors r+

# Objective This PR aims to document the `bevy_asset` crate to complete coverage, while also trying to improve some bits of UX. ### Progress - [x] Root items - [x] `handle` module - [x] `info` module - [x] `path` module - [x] `loader` module - [x] `io` and `filesystem_watcher` module - [x] `assets` module - [x] `asset_server` module - [x] `diagnostic` module - [x] `debug_asset_server` module - [x] Crate level documentation - [x] Add `#![warn(missing_docs)]` lint Coverage: 100% ## Migration Guide - Rename `FileAssetIo::get_root_path` uses to `FileAssetIo::get_base_path` `FileAssetIo::root_path()` is a getter for the `root_path` field, while `FileAssetIo::get_root_path` returned the parent directory of the asset root path, which was the executable's directory unless `CARGO_MANIFEST_DIR` was set. This change solves the ambiguity between the two methods.

bors · 2022-07-12T15:59:18Z

Pull request successfully merged into main.

Build succeeded:

# Objective - `#![warn(missing_docs)]` was added to bevy_asset in #3536 - A method was not documented when targeting wasm ## Solution - Add documentation for it

# Objective This PR aims to document the `bevy_asset` crate to complete coverage, while also trying to improve some bits of UX. ### Progress - [x] Root items - [x] `handle` module - [x] `info` module - [x] `path` module - [x] `loader` module - [x] `io` and `filesystem_watcher` module - [x] `assets` module - [x] `asset_server` module - [x] `diagnostic` module - [x] `debug_asset_server` module - [x] Crate level documentation - [x] Add `#![warn(missing_docs)]` lint Coverage: 100% ## Migration Guide - Rename `FileAssetIo::get_root_path` uses to `FileAssetIo::get_base_path` `FileAssetIo::root_path()` is a getter for the `root_path` field, while `FileAssetIo::get_root_path` returned the parent directory of the asset root path, which was the executable's directory unless `CARGO_MANIFEST_DIR` was set. This change solves the ambiguity between the two methods.

# Objective - `#![warn(missing_docs)]` was added to bevy_asset in bevyengine#3536 - A method was not documented when targeting wasm ## Solution - Add documentation for it

# Objective This PR aims to document the `bevy_asset` crate to complete coverage, while also trying to improve some bits of UX. ### Progress - [x] Root items - [x] `handle` module - [x] `info` module - [x] `path` module - [x] `loader` module - [x] `io` and `filesystem_watcher` module - [x] `assets` module - [x] `asset_server` module - [x] `diagnostic` module - [x] `debug_asset_server` module - [x] Crate level documentation - [x] Add `#![warn(missing_docs)]` lint Coverage: 100% ## Migration Guide - Rename `FileAssetIo::get_root_path` uses to `FileAssetIo::get_base_path` `FileAssetIo::root_path()` is a getter for the `root_path` field, while `FileAssetIo::get_root_path` returned the parent directory of the asset root path, which was the executable's directory unless `CARGO_MANIFEST_DIR` was set. This change solves the ambiguity between the two methods.

# Objective - `#![warn(missing_docs)]` was added to bevy_asset in bevyengine#3536 - A method was not documented when targeting wasm ## Solution - Add documentation for it

# Objective Following discussion on #3536 and #3522, `Handle::as_weak()` takes a type `U`, reinterpreting the handle as of another asset type while keeping the same ID. This is mainly used today in font atlas code. This PR does two things: - Rename the method to `cast_weak()` to make its intent more clear - Actually change the type uuid in the handle if it's not an asset path variant. ## Migration Guide - Rename `Handle::as_weak` uses to `Handle::cast_weak` The method now properly sets the associated type uuid if the handle is a direct reference (e.g. not a reference to an `AssetPath`), so adjust you code accordingly if you relied on the previous behavior.

# Objective This PR aims to document the `bevy_asset` crate to complete coverage, while also trying to improve some bits of UX. ### Progress - [x] Root items - [x] `handle` module - [x] `info` module - [x] `path` module - [x] `loader` module - [x] `io` and `filesystem_watcher` module - [x] `assets` module - [x] `asset_server` module - [x] `diagnostic` module - [x] `debug_asset_server` module - [x] Crate level documentation - [x] Add `#![warn(missing_docs)]` lint Coverage: 100% ## Migration Guide - Rename `FileAssetIo::get_root_path` uses to `FileAssetIo::get_base_path` `FileAssetIo::root_path()` is a getter for the `root_path` field, while `FileAssetIo::get_root_path` returned the parent directory of the asset root path, which was the executable's directory unless `CARGO_MANIFEST_DIR` was set. This change solves the ambiguity between the two methods.

# Objective - `#![warn(missing_docs)]` was added to bevy_asset in bevyengine#3536 - A method was not documented when targeting wasm ## Solution - Add documentation for it

# Objective Following discussion on bevyengine#3536 and bevyengine#3522, `Handle::as_weak()` takes a type `U`, reinterpreting the handle as of another asset type while keeping the same ID. This is mainly used today in font atlas code. This PR does two things: - Rename the method to `cast_weak()` to make its intent more clear - Actually change the type uuid in the handle if it's not an asset path variant. ## Migration Guide - Rename `Handle::as_weak` uses to `Handle::cast_weak` The method now properly sets the associated type uuid if the handle is a direct reference (e.g. not a reference to an `AssetPath`), so adjust you code accordingly if you relied on the previous behavior.

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Jan 3, 2022

alice-i-cecile added A-Assets Load files from disk to use for things like images, models, and sounds C-Docs An addition or correction to our documentation and removed S-Needs-Triage This issue needs to be labelled labels Jan 3, 2022

alice-i-cecile mentioned this pull request Jan 3, 2022

Tracking issue: deny missing docs, one crate at a time #3492

Open

45 tasks

manokara force-pushed the doc/bevy_asset branch from ff11545 to a074e17 Compare January 5, 2022 14:02