search

bonsairobo / building-blocks

A voxel library for real-time applications.
MIT License
369 stars 30 forks source link

Inline Crates and Hide Prelude in Docs #34

Closed zicklag closed 3 years ago

zicklag commented 3 years ago

If you try to search the building-blocks crate on docs.rs, you get no results. This is confusing to users ( or it was for me ), then I realized that the whole contents of the building-blocks crate was re-exports, and that was why search wasn't working.

This change will inline the documentation for the re-exported crates, allowing all of them to be searched at the same time without having to jump between the different crates.

This also hides the prelude from the docs so that you don't get excessive duplicates when searching.

bonsairobo commented 3 years ago

If you try to search the building-blocks crate on docs.rs, you get no results

I think I fixed this after version 0.7.0. Have you tried building the docs on main?

This also hides the prelude from the docs so that you don't get excessive duplicates when searching.

I tried cargo doc --open with these changes but I still get duplicates. I'm not sure why though.

duplicates

zicklag commented 3 years ago

I think I fixed this after version 0.7.0. Have you tried building the docs on main?

Oh, yeah, you're right! I should have noticed that. :)

I tried cargo doc --open with these changes but I still get duplicates. I'm not sure why though.

Yeah, those are because of the re-exports in the different modules. For instance, building_blocks::mesh::greedy_quads::greedy_quads function is re-exported at building_blocks::mesh::greedy_quads. Unfortunatley that's not something we can fix without something like the un-implemented #[doc(canonical)] annotation, unless you are willing to hide the re-exports from the docs, but I think that would be confusing, as I'm assuming the reason that they are re-exported was to help discoverability and to make it easier to get to.

bonsairobo commented 3 years ago

Yea honestly I'm not super knowledgeable about how the rust docs work. I've struggled with it in the past. But I'd like to understand better and come up with a consistent strategy for re-exports.

I think I can eliminate some duplicates by making the submodules of building_blocks_mesh private. All symbols are re-exported from those submodules anyway, and I don't have any module-level documentation.