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

Inconsistent crate features documentation #1434

Closed
edmorley opened this issue Feb 12, 2024 · 2 comments · Fixed by #1455
Closed

Inconsistent crate features documentation #1434

edmorley opened this issue Feb 12, 2024 · 2 comments · Fixed by #1455

Comments

@edmorley
Copy link
Contributor

PR #1343 added a new now feature, however, this feature is only documented in README.md and not in the features list on docs.rs.

Compare README.md:

chrono/README.md

Lines 49 to 67 in 3016c30

## Crate features
Default features:
* `alloc`: Enable features that depend on allocation (primarily string formatting)
* `std`: Enables functionality that depends on the standard library. This is a superset of `alloc`
and adds interoperation with standard library types and traits.
* `clock`: Enables reading the local timezone (`Local`). This is a superset of `now`.
* `now`: Enables reading the system time (`now`)
* `wasmbind`: Interface with the JS Date API for the `wasm32` target.
Optional features:
* `serde`: Enable serialization/deserialization via serde.
* `rkyv`: Enable serialization/deserialization via rkyv.
* `rustc-serialize`: Enable serialization/deserialization via rustc-serialize (deprecated).
* `arbitrary`: construct arbitrary instances of a type with the Arbitrary crate.
* `unstable-locales`: Enable localization. This adds various methods with a `_localized` suffix.
The implementation and API may change or even be removed in a patch release. Feedback welcome.

With the crate rustdocs:

chrono/src/lib.rs

Lines 20 to 44 in 3016c30

//! ### Features
//!
//! Chrono supports various runtime environments and operating systems, and has
//! several features that may be enabled or disabled.
//!
//! Default features:
//!
//! - `alloc`: Enable features that depend on allocation (primarily string formatting)
//! - `std`: Enables functionality that depends on the standard library. This
//! is a superset of `alloc` and adds interoperation with standard library types
//! and traits.
//! - `clock`: Enables reading the system time (`now`) that depends on the standard library for
//! UNIX-like operating systems and the Windows API (`winapi`) for Windows.
//! - `wasmbind`: Interface with the JS Date API for the `wasm32` target.
//!
//! Optional features:
//!
//! - [`serde`][]: Enable serialization/deserialization via serde.
//! - `rkyv`: Enable serialization/deserialization via rkyv.
//! - `arbitrary`: construct arbitrary instances of a type with the Arbitrary crate.
//! - `unstable-locales`: Enable localization. This adds various methods with a
//! `_localized` suffix. The implementation and API may change or even be
//! removed in a patch release. Feedback welcome.
//! - `oldtime`: this feature no langer has a function, but once offered compatibility with the
//! `time` 0.1 crate.

I see there are also some differences in the other features listed under "optional features" too.

@pitdicker
Copy link
Collaborator

@edmorley Thank you for reporting this. Would you be interested in making a PR to straighten it out?
We should also document or at least mist the extra rkyv features.

edmorley added a commit to edmorley/chrono that referenced this issue Feb 23, 2024
The `chrono` crate makes use of several Cargo features:
https://github.com/chronotope/chrono/blob/02c68d69a1ff8e6461384a770b87737b5096eae3/Cargo.toml#L19-L46

These features are documented in both `README.md` and the rustdocs
in `lib.rs, however, the lists in each place were missing some features
and also inconsistent in their descriptions.

I've also removed the unused `[wasm-bindgen]` link definition, and
made the usage of code blocks vs links more consistent.

Fixes chronotope#1434.
edmorley added a commit to edmorley/chrono that referenced this issue Feb 23, 2024
The `chrono` crate makes use of several Cargo features:
https://github.com/chronotope/chrono/blob/02c68d69a1ff8e6461384a770b87737b5096eae3/Cargo.toml#L19-L46

These features are documented in both `README.md` and the rustdocs
in `lib.rs, however, the lists in each place were missing some features
and also inconsistent in their descriptions.

I've also removed the unused `[wasm-bindgen]` link definition.

Fixes chronotope#1434.
@edmorley
Copy link
Contributor Author

I've opened #1455 - happy to make further wording/... adjustments if needed (or feel free to push to the PR directly if easier) :-)

edmorley added a commit to edmorley/chrono that referenced this issue Feb 23, 2024
The `chrono` crate makes use of several Cargo features:
https://github.com/chronotope/chrono/blob/02c68d69a1ff8e6461384a770b87737b5096eae3/Cargo.toml#L19-L46

These features are documented in both `README.md` and the rustdocs
in `lib.rs, however, the lists in each place were missing some features
and also inconsistent in their descriptions.

I've also removed the unused `[wasm-bindgen]` link definition.

Fixes chronotope#1434.
edmorley added a commit to edmorley/chrono that referenced this issue Feb 23, 2024
The `chrono` crate makes use of several Cargo features:
https://github.com/chronotope/chrono/blob/02c68d69a1ff8e6461384a770b87737b5096eae3/Cargo.toml#L19-L46

These features are documented in both `README.md` and the rustdocs
in `lib.rs, however, the lists in each place were missing some features
and also inconsistent in their descriptions.

I've also removed the unused `[wasm-bindgen]` link definition.

Fixes chronotope#1434.
pitdicker pushed a commit that referenced this issue Feb 26, 2024
The `chrono` crate makes use of several Cargo features:
https://github.com/chronotope/chrono/blob/02c68d69a1ff8e6461384a770b87737b5096eae3/Cargo.toml#L19-L46

These features are documented in both `README.md` and the rustdocs
in `lib.rs, however, the lists in each place were missing some features
and also inconsistent in their descriptions.

I've also removed the unused `[wasm-bindgen]` link definition.

Fixes #1434.
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

Successfully merging a pull request may close this issue.

2 participants