Skip to content

Properly set rustdoc attr. Closing #2950 #2975

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.

Sign up for GitHub

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

Closed
wants to merge 6 commits into from
Closed

Properly set rustdoc attr. Closing #2950 #2975

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9ffb40b
Added necessary additions
umgefahren Oct 3, 2022
60a1c35
Added some doc_cfg
umgefahren Oct 4, 2022
de1d39a
Merge branch 'master' into properly-set-rustdoc-attr
umgefahren Oct 4, 2022
1520174
Removed unnecessary things from Cargo.tomls
umgefahren Oct 4, 2022
6c9a646
Implemented docsrs changes over all crates and subcrates
umgefahren Oct 4, 2022
10258c3
Merge branch 'master' into properly-set-rustdoc-attr
umgefahren Oct 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,6 @@ rsa = ["libp2p-core/rsa"]
ecdsa = ["libp2p-core/ecdsa"]
serde = ["libp2p-core/serde", "libp2p-kad?/serde", "libp2p-gossipsub?/serde"]

[package.metadata.docs.rs]
all-features = true

[dependencies]
bytes = "1"
futures = "0.3.1"
Expand Down Expand Up @@ -201,3 +198,8 @@ required-features = ["full"]
[[example]]
name = "distributed-key-value-store"
required-features = ["full"]

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add a newline so this icon goes away? 😇

5 changes: 5 additions & 0 deletions core/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,3 +64,8 @@ serde = ["multihash/serde-codec", "dep:serde"]
[[bench]]
name = "peer_id"
harness = false

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
39 changes: 26 additions & 13 deletions core/src/identity.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,15 @@
//! (e.g. [ed25519 binary format](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.5)).
//! All key types have functions to enable conversion to/from their binary representations.

#[cfg(feature = "ecdsa")]
#[cfg(any(feature = "ecdsa", docsrs))]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are we combining these with any?

Shouldn't the regular feature be enough?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, you are right. Only if it's compiled with all features though, but yes.

#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
pub mod ecdsa;
pub mod ed25519;
#[cfg(all(feature = "rsa", not(target_arch = "wasm32")))]
#[cfg(any(all(feature = "rsa", not(target_arch = "wasm32")), docsrs))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "rsa", not(target_arch = "wasm32")))))]
pub mod rsa;
#[cfg(feature = "secp256k1")]
#[cfg(any(feature = "secp256k1", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "secp256k1")))]
pub mod secp256k1;

pub mod error;
Expand Down Expand Up @@ -69,13 +72,16 @@ pub enum Keypair {
/// An Ed25519 keypair.
Ed25519(ed25519::Keypair),
/// An RSA keypair.
#[cfg(all(feature = "rsa", not(target_arch = "wasm32")))]
#[cfg(any(all(feature = "rsa", not(target_arch = "wasm32")), docsrs))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "rsa", not(target_arch = "wasm32")))))]
Rsa(rsa::Keypair),
/// A Secp256k1 keypair.
#[cfg(feature = "secp256k1")]
#[cfg(any(feature = "secp256k1", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "secp256k1")))]
Secp256k1(secp256k1::Keypair),
/// An ECDSA keypair.
#[cfg(feature = "ecdsa")]
#[cfg(any(feature = "ecdsa", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
Ecdsa(ecdsa::Keypair),
}

Expand All @@ -86,13 +92,15 @@ impl Keypair {
}

/// Generate a new Secp256k1 keypair.
#[cfg(feature = "secp256k1")]
#[cfg(any(feature = "secp256k1", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "secp256k1")))]
pub fn generate_secp256k1() -> Keypair {
Keypair::Secp256k1(secp256k1::Keypair::generate())
}

/// Generate a new ECDSA keypair.
#[cfg(feature = "ecdsa")]
#[cfg(any(feature = "ecdsa", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
pub fn generate_ecdsa() -> Keypair {
Keypair::Ecdsa(ecdsa::Keypair::generate())
}
Expand All @@ -101,7 +109,8 @@ impl Keypair {
/// format (i.e. unencrypted) as defined in [RFC5208].
///
/// [RFC5208]: https://tools.ietf.org/html/rfc5208#section-5
#[cfg(all(feature = "rsa", not(target_arch = "wasm32")))]
#[cfg(any(all(feature = "rsa", not(target_arch = "wasm32")), docsrs))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "rsa", not(target_arch = "wasm32")))))]
pub fn rsa_from_pkcs8(pkcs8_der: &mut [u8]) -> Result<Keypair, DecodingError> {
rsa::Keypair::from_pkcs8(pkcs8_der).map(Keypair::Rsa)
}
Expand All @@ -110,7 +119,8 @@ impl Keypair {
/// structure as defined in [RFC5915].
///
/// [RFC5915]: https://tools.ietf.org/html/rfc5915
#[cfg(feature = "secp256k1")]
#[cfg(any(feature = "secp256k1", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "secp256k1")))]
pub fn secp256k1_from_der(der: &mut [u8]) -> Result<Keypair, DecodingError> {
secp256k1::SecretKey::from_der(der)
.map(|sk| Keypair::Secp256k1(secp256k1::Keypair::from(sk)))
Expand Down Expand Up @@ -218,14 +228,17 @@ impl zeroize::Zeroize for keys_proto::PrivateKey {
pub enum PublicKey {
/// A public Ed25519 key.
Ed25519(ed25519::PublicKey),
#[cfg(all(feature = "rsa", not(target_arch = "wasm32")))]
/// A public RSA key.
#[cfg(any(all(feature = "rsa", not(target_arch = "wasm32")), docsrs))]
#[cfg_attr(docsrs, doc(cfg(all(feature = "rsa", not(target_arch = "wasm32")))))]
Rsa(rsa::PublicKey),
#[cfg(feature = "secp256k1")]
/// A public Secp256k1 key.
#[cfg(any(feature = "secp256k1", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "secp256k1")))]
Secp256k1(secp256k1::PublicKey),
/// A public ECDSA key.
#[cfg(feature = "ecdsa")]
#[cfg(any(feature = "ecdsa", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "ecdsa")))]
Ecdsa(ecdsa::PublicKey),
}

Expand Down
2 changes: 2 additions & 0 deletions core/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@
//! define how to upgrade each individual substream to use a protocol.
//! See the `upgrade` module.

#![cfg_attr(docsrs, feature(doc_cfg))]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These seems like it is a left over from another attempt at solving this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No I don't think so. This turns the required feature gate on. I.e. #[doc(cfg(...))].

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, my bad! Thanks for clarifying!


#[allow(clippy::derive_partial_eq_without_eq)]
mod keys_proto {
include!(concat!(env!("OUT_DIR"), "/keys_proto.rs"));
Expand Down
8 changes: 5 additions & 3 deletions core/src/peer_id.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ use rand::Rng;
use std::{convert::TryFrom, fmt, str::FromStr};
use thiserror::Error;

#[cfg(feature = "serde")]
#[cfg(any(feature = "serde", docsrs))]
use serde::{Deserialize, Serialize};

/// Public keys with byte-lengths smaller than `MAX_INLINE_KEY_LENGTH` will be
Expand Down Expand Up @@ -179,7 +179,8 @@ impl From<PeerId> for Vec<u8> {
}
}

#[cfg(feature = "serde")]
#[cfg(any(feature = "serde", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl Serialize for PeerId {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
Expand All @@ -193,7 +194,8 @@ impl Serialize for PeerId {
}
}

#[cfg(feature = "serde")]
#[cfg(any(feature = "serde", docsrs))]
#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
impl<'de> Deserialize<'de> for PeerId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
Expand Down
4 changes: 4 additions & 0 deletions misc/keygen/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,3 +15,7 @@ serde = { version = "1.0.136", features = ["derive"] }
serde_json = "1.0.79"
libp2p-core = { version = "0.37.0", path = "../../core" }
base64 = "0.13.0"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions misc/metrics/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,7 @@ futures = "0.3.1"
libp2p = { path = "../..", features = ["full"] }
hyper = { version="0.14", features = ["server", "tcp", "http1"] }
tokio = { version = "1", features = ["rt-multi-thread"] }
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions misc/multistream-select/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,7 @@ libp2p = { path = "../..", features = ["full"] }
quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }
rand = "0.8"
rw-stream-sink = { version = "0.3.0", path = "../../misc/rw-stream-sink" }
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions misc/prost-codec/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,7 @@ unsigned-varint = { version = "0.7", features = ["asynchronous_codec"] }

[dev-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions misc/rw-stream-sink/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,7 @@ static_assertions = "1"

[dev-dependencies]
async-std = "1.0"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions muxers/mplex/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,7 @@ quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }
[[bench]]
name = "split_send_size"
harness = false
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions muxers/yamux/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,8 @@ parking_lot = "0.12"
thiserror = "1.0"
yamux = "0.10.0"
log = "0.4"

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions protocols/autonat/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,8 @@ async-std = { version = "1.10", features = ["attributes"] }
env_logger = "0.9"
clap = {version = "3.1.6", features = ["derive"]}
libp2p = { path = "../..", features = ["full"] }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/dcutr/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,7 @@ env_logger = "0.9.0"
libp2p = { path = "../..", features = ["full"] }
rand = "0.8"
clap = {version = "3.1.6", features = ["derive"]}
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/floodsub/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,7 @@ smallvec = "1.6.1"

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/gossipsub/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,7 @@ derive_builder = "0.11.1"

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/identify/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,7 @@ libp2p = { path = "../..", features = ["full"] }

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/kad/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,3 +43,7 @@ prost-build = "0.11"

[features]
serde = ["dep:serde", "bytes/serde"]
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/mdns/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,7 @@ required-features = ["async-io"]
name = "use-tokio"
required-features = ["tokio"]

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
Comment on lines +49 to +52
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it may be worthwhile to just copy-paste this into all manifests? Otherwise, if we add features later we may forget about this.

We can include a link to this documentation to make this a bit easier to understand.

5 changes: 5 additions & 0 deletions protocols/ping/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,8 @@ void = "1.0"
async-std = "1.6.2"
libp2p = { path = "../..", features = ["full"] }
quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/relay/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,7 @@ env_logger = "0.9.0"
libp2p = { path = "../..", features = ["full"] }
quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }
clap = {version = "3.1.6", features = ["derive"]}
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions protocols/rendezvous/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,7 @@ tokio = { version = "1.15", features = [ "rt-multi-thread", "time", "macros", "s

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions protocols/request-response/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,8 @@ async-std = "1.6.2"
env_logger = "0.9.0"
libp2p = { path = "../..", features = ["full"] }
rand = "0.8"

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
1 change: 1 addition & 0 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@

#![doc(html_logo_url = "https://libp2p.io/img/logo_small.png")]
#![doc(html_favicon_url = "https://libp2p.io/img/favicon.png")]
#![cfg_attr(docsrs, feature(doc_cfg))]

pub use bytes;
pub use futures;
Expand Down
4 changes: 4 additions & 0 deletions swarm-derive/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,7 @@ libp2p = { path = "..", features = ["full"] }
either = "1.6.0"
futures = "0.3.1"
void = "1"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions swarm/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,8 @@ async-std = { version = "1.6.2", features = ["attributes"] }
env_logger = "0.9"
libp2p = { path = "..", features = ["full"] }
quickcheck = { package = "quickcheck-ext", path = "../misc/quickcheck-ext" }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions transports/deflate/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,8 @@ async-std = "1.6.2"
libp2p = { path = "../..", features = ["full"] }
quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }
rand = "0.8"

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions transports/dns/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,7 @@ tokio = ["trust-dns-resolver/tokio-runtime"]
# available for `tokio`.
tokio-dns-over-rustls = ["tokio", "trust-dns-resolver/dns-over-rustls"]
tokio-dns-over-https-rustls = ["tokio", "trust-dns-resolver/dns-over-https-rustls"]
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions transports/noise/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,7 @@ ed25519-compact = "1.0.11"

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions transports/plaintext/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,7 @@ rand = "0.8"

[build-dependencies]
prost-build = "0.11"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
5 changes: 5 additions & 0 deletions transports/pnet/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,8 @@ pin-project = "1.0.2"

[dev-dependencies]
quickcheck = { package = "quickcheck-ext", path = "../../misc/quickcheck-ext" }

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
4 changes: 4 additions & 0 deletions transports/tcp/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,7 @@ async-io = ["async-io-crate"]
async-std = { version = "1.6.5", features = ["attributes"] }
tokio-crate = { package = "tokio", version = "1.0.1", default-features = false, features = ["net", "rt", "macros"] }
env_logger = "0.9.0"
[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]
rustc-args = ["--cfg", "docsrs"]
Loading