amethyst / specs

Specs - Parallel ECS
https://amethyst.github.io/specs/
Apache License 2.0
2.49k stars 219 forks source link

Add necessity of feature flag serde to api documentation for saveload #760

Open andreas-wolf opened 2 years ago

andreas-wolf commented 2 years ago

Description

The saveload documentation states: saveload is a module that provides mechanisms to serialize and deserialize a World, it makes use of the popular [serde](https://docs.rs/serde) library and requires the feature flag serde to be enabled for specs in your Cargo.toml file.

The API documentation does not mention this fact, but it was at least for me the first google search hit when I got unresolved import specs::saveload. Maybe it would even be worth it to add the information to the Troubleshooting section

Motivation

I had to search quite a long time to find that information. I assume I'm not the only person to search the API than to read the tutorial.

Drawbacks

None

xMAC94x commented 2 years ago

Hi @andreas-wolf can you prepare a PR that mabee adds a little block here: https://github.com/amethyst/specs/blob/master/docs/tutorials/src/13_saveload.md which says: `feature = ["serde"] is needed for saveload to work.

Unluckily ouir api also doesnt mention it on the structs itself, as the check is on the module: https://github.com/amethyst/specs/blob/master/src/lib.rs#L202 though tbh it kind of mentions it directly in the api doc that its going to use specs

Imberflur commented 11 months ago

We might be able to use this https://doc.rust-lang.org/rustdoc/unstable-features.html#doc_auto_cfg-automatically-generate-doccfg

Also see here for examples of how to only enable the necessary nightly feature when docs.rs is building the docs: https://stackoverflow.com/a/61417700