Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
andreas-wolf opened this issue Sep 6, 2022 · 2 comments

Comments

@andreas-wolf
Copy link

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

  • Is it a breaking change? No
  • Can it impact performance, learnability, etc? Yes
@xMAC94x
Copy link
Collaborator

xMAC94x commented Sep 7, 2022

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
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants