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

Use #[cfg(doc)] declarations to include WASM-specific functionality on native doc builds. #54

Closed
ajrcarey opened this issue Oct 14, 2022 · 3 comments
Assignees

Comments

@ajrcarey
Copy link
Owner

Currently, when running cargo doc on a native platform, documentation for WASM-specific functionality is not included. (This is the case on docs.rs as well.)

Rework the inline documentation of WASM-specific items using #[cfg(doc)] declarations, so that cargo doc generates documentation for WASM-specific functionality as well.

@ajrcarey
Copy link
Owner Author

The generation of multi-target documentation in a single run of cargo doc is a long-standing problem; for context, see rust-lang/rust#1998 and rust-lang/rust#43348.

Recent builds of rustdoc pass a special cfg target setting, doc, that can be detected during documentation generation. We can change our current #[cfg(target_arch = "wasm32")] declarations to #[cfg(any(doc, target_arch = "wasm32"))] to have those functions included in our documentation builds.

@ajrcarey
Copy link
Owner Author

ajrcarey commented Oct 14, 2022

Certain types that are imported only when compiling to WASM - items from the js_sys and wasm_bindgen crates, for instance - must be available when generating documentation as well. Ideally, applying the doc target to Cargo.toml would automatically include the items we need, but this does not work; probably those crates are entirely wrapped with WASM-specific declarations, so even if we include them successfully with Cargo.toml, they are not exposed except when building on WASM. After thinking about it for a while, I decided the simplest solution was to create empty dummy structs like so:

#[cfg(doc)]
struct JsValue;

This is sufficient for the call to cargo doc to succeed, which is all that we need.

@ajrcarey
Copy link
Owner Author

Updated #[cfg()] declarations for all WASM-specific functions. Bumped crate version number to 0.7.23. Updated README.md.

ajrcarey pushed a commit that referenced this issue Oct 14, 2022
@ajrcarey ajrcarey self-assigned this Mar 10, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant