document features (#512)

frost-core/Cargo.toml

@@ -18,10 +18,12 @@ keywords = ["cryptography", "crypto", "threshold", "signature", "schnorr"]
 description = "Types and traits to support implementing Flexible Round-Optimized Schnorr Threshold signature schemes (FROST)."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 byteorder = "1.4"
+document-features = "0.2.7"
 debugless-unwrap = "0.0.4"
 derive-getters = "0.3.0"
 hex = "0.4.3"
@@ -46,9 +48,15 @@ rand_chacha = "0.3"
 serde_json = "1.0"
 
 [features]
-nightly = []
 default = []
+#! ## Features
+## Expose internal types, which do not have SemVer guarantees. This is an advanced
+## feature which can be useful if you need to build a modified version of FROST.
+## The docs won't list them, you will need to check the source code.
 internals = []
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["dep:serde", "dep:serdect"]
 # Exposes ciphersuite-generic tests for other crates to use
 test-impl = ["proptest", "serde_json", "criterion"]

frost-core/src/frost.rs

@@ -97,6 +97,7 @@ where
 ///
 /// [`compute_binding_factors`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-4.4
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 pub(crate) fn compute_binding_factor_list<C>(
     signing_package: &SigningPackage<C>,
     group_public: &VerifyingKey<C>,
@@ -146,6 +147,7 @@ where
 ///
 /// If `x` is None, it uses 0 for it (since Identifiers can't be 0)
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 fn compute_lagrange_coefficient<C: Ciphersuite>(
     x_set: &BTreeSet<Identifier<C>>,
     x: Option<Identifier<C>>,
@@ -190,6 +192,7 @@ fn compute_lagrange_coefficient<C: Ciphersuite>(
 ///
 /// [`derive_interpolating_value()`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-polynomials
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 fn derive_interpolating_value<C: Ciphersuite>(
     signer_id: &Identifier<C>,
     signing_package: &SigningPackage<C>,
@@ -268,6 +271,7 @@ where
     /// Compute the preimages to H1 to compute the per-signer binding factors
     // We separate this out into its own method so it can be tested
     #[cfg_attr(feature = "internals", visibility::make(pub))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
     pub fn binding_factor_preimages(
         &self,
         group_public: &VerifyingKey<C>,
@@ -325,6 +329,7 @@ where
 ///
 /// [`compute_group_commitment`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-4.5
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 fn compute_group_commitment<C>(
     signing_package: &SigningPackage<C>,
     binding_factor_list: &BindingFactorList<C>,

frost-core/src/frost/round1.rs

@@ -302,6 +302,7 @@ where
     ///
     /// [signature commitment share]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-share-verificatio
     #[cfg_attr(feature = "internals", visibility::make(pub))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
     pub(super) fn to_group_commitment_share(
         self,
         binding_factor: &frost::BindingFactor<C>,

frost-core/src/frost/round2.rs

@@ -81,6 +81,7 @@ where
     ///
     /// [`verify_signature_share`]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-share-verificatio
     #[cfg_attr(feature = "internals", visibility::make(pub))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
     pub(crate) fn verify(
         &self,
         identifier: Identifier<C>,
@@ -156,6 +157,7 @@ where
 
 /// Compute the signature share for a signing operation.
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 fn compute_signature_share<C: Ciphersuite>(
     signer_nonces: &round1::SigningNonces<C>,
     binding_factor: BindingFactor<C>,

frost-core/src/lib.rs

@@ -2,10 +2,13 @@
 // It's emitting false positives; see https://github.com/rust-lang/rust-clippy/issues/9413
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![deny(missing_docs)]
-#![doc = include_str!("../README.md")]
 #![forbid(unsafe_code)]
 #![deny(clippy::indexing_slicing)]
 #![deny(clippy::unwrap_used)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc = include_str!("../README.md")]
+#![doc = document_features::document_features!()]
 
 use std::{
     default::Default,
@@ -98,6 +101,7 @@ pub type Scalar<C> = <<<C as Ciphersuite>::Group as Group>::Field as Field>::Sca
 
 #[cfg(feature = "serde")]
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 /// Helper struct to serialize a Scalar.
 pub(crate) struct ScalarSerialization<C: Ciphersuite>(
     pub <<<C as Ciphersuite>::Group as Group>::Field as Field>::Serialization,
@@ -374,6 +378,7 @@ where
 /// [FROST]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#name-signature-challenge-computa
 /// [RFC]: https://www.ietf.org/archive/id/draft-irtf-cfrg-frost-14.html#section-3.2
 #[cfg_attr(feature = "internals", visibility::make(pub))]
+#[cfg_attr(docsrs, doc(cfg(feature = "internals")))]
 fn challenge<C>(R: &Element<C>, verifying_key: &Element<C>, msg: &[u8]) -> Challenge<C>
 where
     C: Ciphersuite,

frost-ed25519/Cargo.toml

@@ -19,10 +19,12 @@ keywords = ["cryptography", "crypto", "ed25519", "threshold", "signature"]
 description = "A Schnorr signature scheme over Ed25519 that supports FROST."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 curve25519-dalek = { version = "=4.0.0", features = ["rand_core"] }
+document-features = "0.2.7"
 frost-core = { path = "../frost-core", version = "0.6.0" }
 rand_core = "0.6"
 sha2 = "0.10.2"
@@ -42,6 +44,10 @@ serde_json = "1.0"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 
 [lib]

frost-ed25519/src/lib.rs

@@ -1,6 +1,9 @@
 #![allow(non_snake_case)]
 #![deny(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
+#![doc = document_features::document_features!()]
 
 use std::collections::HashMap;
 

frost-ed448/Cargo.toml

@@ -18,9 +18,11 @@ keywords = ["cryptography", "crypto", "ed448", "threshold", "signature"]
 description = "A Schnorr signature scheme over Ed448 that supports FROST."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
+document-features = "0.2.7"
 ed448-goldilocks = { version = "0.9.0" }
 frost-core = { path = "../frost-core", version = "0.6.0" }
 rand_core = "0.6"
@@ -40,6 +42,10 @@ serde_json = "1.0"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 
 [lib]

frost-ed448/src/lib.rs

@@ -1,6 +1,9 @@
 #![allow(non_snake_case)]
 #![deny(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
+#![doc = document_features::document_features!()]
 
 use std::collections::HashMap;
 

frost-p256/Cargo.toml

@@ -19,9 +19,11 @@ keywords = ["cryptography", "crypto", "threshold", "signature"]
 description = "A Schnorr signature scheme over the NIST P-256 curve that supports FROST."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
+document-features = "0.2.7"
 p256 = { version = "0.13.0", features = ["hash2curve"] }
 frost-core = { path = "../frost-core", version = "0.6.0" }
 rand_core = "0.6"
@@ -41,6 +43,10 @@ serde_json = "1.0"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 
 [lib]

frost-p256/src/lib.rs

@@ -1,6 +1,9 @@
 #![allow(non_snake_case)]
 #![deny(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
+#![doc = document_features::document_features!()]
 
 use std::collections::HashMap;
 

frost-rerandomized/Cargo.toml

@@ -16,10 +16,12 @@ keywords = ["cryptography", "threshold", "signature", "schnorr", "randomized"]
 description = "Types and traits to support implementing a re-randomized variant of Flexible Round-Optimized Schnorr Threshold signature schemes (FROST)."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 derive-getters = "0.3.0"
+document-features = "0.2.7"
 frost-core = { path = "../frost-core", version = "0.6.0", features = ["internals"] }
 rand_core = "0.6"
 
@@ -28,6 +30,10 @@ rand_core = "0.6"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 # Exposes ciphersuite-generic tests for other crates to use
 test-impl = ["frost-core/test-impl"]

frost-ristretto255/Cargo.toml

@@ -15,10 +15,12 @@ keywords = ["cryptography", "crypto", "ristretto", "threshold", "signature"]
 description = "A Schnorr signature scheme over the prime-order Ristretto group that supports FROST."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
 curve25519-dalek = { version = "=4.0.0", features = ["serde", "rand_core"] }
+document-features = "0.2.7"
 frost-core = { path = "../frost-core", version = "0.6.0" }
 rand_core = "0.6"
 sha2 = "0.10.2"
@@ -37,6 +39,10 @@ serde_json = "1.0"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 
 [lib]

frost-secp256k1/Cargo.toml

@@ -18,9 +18,11 @@ keywords = ["cryptography", "crypto", "threshold", "signature"]
 description = "A Schnorr signature scheme over the secp256k1 curve that supports FROST."
 
 [package.metadata.docs.rs]
-features = ["nightly"]
+features = ["serde"]
+rustdoc-args = ["--cfg", "docsrs"]
 
 [dependencies]
+document-features = "0.2.7"
 frost-core = { path = "../frost-core", version = "0.6.0" }
 k256 = { version = "0.13.0", features = ["arithmetic", "expose-field", "hash2curve"] }
 rand_core = "0.6"
@@ -40,6 +42,10 @@ serde_json = "1.0"
 [features]
 nightly = []
 default = []
+#! ## Features
+## Enable `serde` support for types that need to be communicated. You
+## can use `serde` to serialize structs with any encoder that supports
+## `serde` (e.g. JSON with `serde_json`).
 serde = ["frost-core/serde"]
 
 [lib]

frost-secp256k1/src/lib.rs

@@ -1,6 +1,9 @@
 #![allow(non_snake_case)]
 #![deny(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![doc = include_str!("../README.md")]
+#![doc = document_features::document_features!()]
 
 use std::collections::HashMap;