Merge pull request dalek-cryptography#440 from dalek-cryptography/doc…

…s-cleanup

CHANGELOG.md

@@ -5,6 +5,8 @@ major series.
 
 ## 4.x series
 
+* Migrate documentation to docs.rs hosted
+* Fix backend documentation generation
 * Deprecate `EdwardsPoint::hash_from_bytes` and rename it `EdwardsPoint::nonspect_map_to_curve`
 * Fix panic when `Ristretto::double_and_compress_batch` receives the identity point
 * Remove `byteorder` dependency

Cargo.toml

@@ -24,9 +24,8 @@ exclude = [
 ]
 
 [package.metadata.docs.rs]
-# Disabled for now since this is borked; tracking https://github.com/rust-lang/docs.rs/issues/302
-# rustdoc-args = ["--html-in-header", ".cargo/registry/src/github.com-1ecc6299db9ec823/curve25519-dalek-0.13.2/rustdoc-include-katex-header.html"]
-features = ["nightly", "simd_backend"]
+rustdoc-args = ["--html-in-header", "docs/assets/rustdoc-include-katex-header.html", "--cfg", "docsrs"]
+features = ["serde", "simd_backend"]
 
 [badges]
 travis-ci = { repository = "dalek-cryptography/curve25519-dalek", branch = "master"}

Makefile

@@ -1,8 +1,8 @@
-FEATURES := nightly simd_backend
+FEATURES := simd_backend serde
 
 doc:
-	cargo rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html
+	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --cfg docsrs
 
 doc-internal:
-	cargo rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items
+	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items --cfg docsrs
 

README.md

@@ -1,10 +1,12 @@
 
 # curve25519-dalek [![](https://img.shields.io/crates/v/curve25519-dalek.svg)](https://crates.io/crates/curve25519-dalek) [![](https://img.shields.io/badge/dynamic/json.svg?label=docs&uri=https%3A%2F%2Fcrates.io%2Fapi%2Fv1%2Fcrates%2Fcurve25519-dalek%2Fversions&query=%24.versions%5B0%5D.num&colorB=4F74A6)](https://doc.dalek.rs) [![](https://travis-ci.org/dalek-cryptography/curve25519-dalek.svg?branch=master)](https://travis-ci.org/dalek-cryptography/curve25519-dalek)
 
+<p style="float: right">
 <img
- width="33%"
- align="right"
+ width="300px"
+ alt="dalek-cryptography logo: a dalek with edwards curves as sparkles coming out of its radar-schnozzley blaster thingies"
  src="https://doc.dalek.rs/assets/dalek-logo-clear.png"/>
+</p>
 
 **A pure-Rust implementation of group operations on Ristretto and Curve25519.**
 
@@ -246,6 +248,6 @@ contributions.
 [docs-external]: https://doc.dalek.rs/curve25519_dalek/
 [docs-internal]: https://doc-internal.dalek.rs/curve25519_dalek/
 [criterion]: https://github.com/japaric/criterion.rs
-[parallel_doc]: https://doc-internal.dalek.rs/curve25519_dalek/backend/vector/avx2/index.html
+[parallel_doc]: https://docs.rs/curve25519-dalek/latest/curve25519_dalek/backend/vector/index.html
 [subtle_doc]: https://doc.dalek.rs/subtle/
 [fiat-crypto]: https://github.com/mit-plv/fiat-crypto

docs/parallel-formulas.md

@@ -145,16 +145,16 @@ This costs \\( 2\mathbf M + 1 \mathbf D\\).
 
 ## Readdition
 
-If the point \\( P_2 = (X\_2 : Y\_2 : Z\_2 : T\_2) \\) is fixed, we
+If the point \\( P\_2 = (X\_2 : Y\_2 : Z\_2 : T\_2) \\) is fixed, we
 can cache the multiplication of the curve constants by computing
 $$
 \begin{aligned}
-(S\_2' &&,&& S\_3' &&,&& Z\_2' &&,&& T\_2' )
+(S\_2\' &&,&& S\_3\' &&,&& Z\_2\' &&,&& T\_2\' )
 &\gets
 (d\_2 \cdot (Y\_2 - X\_2)&&,&& d\_2 \cdot (Y\_1 + X\_1)&&,&& 2d\_2 \cdot Z\_2 &&,&& 2d\_1 \cdot T\_2).
 \end{aligned}
 $$
-This costs \\( 1\mathbf D\\); with \\( (S\_2', S\_3', Z\_2', T\_2')\\)
+This costs \\( 1\mathbf D\\); with \\( (S\_2\', S\_3\', Z\_2\', T\_2\')\\)
 in hand, the addition formulas above become
 $$
 \begin{aligned}
@@ -164,7 +164,7 @@ $$
 \\\\
 (S\_8    &&,&& S\_9    &&,&& S\_{10} &&,&& S\_{11} )
 &\gets
-(S\_0 \cdot S\_2' &&,&& S\_1 \cdot S\_3'&&,&& Z\_1 \cdot Z\_2' &&,&& T\_1 \cdot T\_2')
+(S\_0 \cdot S\_2\' &&,&& S\_1 \cdot S\_3\'&&,&& Z\_1 \cdot Z\_2\' &&,&& T\_1 \cdot T\_2\')
 \\\\
 (S\_{12} &&,&& S\_{13} &&,&& S\_{14} &&,&& S\_{15})
 &\gets
@@ -207,7 +207,7 @@ $$
 (S\_8 \cdot S\_9 &&,&& S\_5 \cdot S\_6 &&,&& S\_8 \cdot S\_6 &&,&& S\_5 \cdot S\_9)
 \end{aligned}
 $$
-to obtain \\( P\_3 = (X\_3 : Y\_3 : Z\_3 : T\_3) = [2]P\_1 \\).
+to obtain \\( P\_3 = (X\_3 : Y\_3 : Z\_3 : T\_3) = \[2\]P\_1 \\).
 
 The intermediate step between the squaring and multiplication requires
 a long chain of additions.  For the IFMA-based implementation, this is not a problem; for the AVX2-based implementation, it is, but with some care and finesse, it's possible to arrange the computation without requiring an intermediate reduction.
@@ -327,7 +327,7 @@ There are several directions for future improvement:
 [sandy2x]: https://eprint.iacr.org/2015/943.pdf
 [avx2trac]: https://trac.torproject.org/projects/tor/ticket/8897#comment:28
 [hwcd08]: https://www.iacr.org/archive/asiacrypt2008/53500329/53500329.pdf
-[curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html
+[curve_models]: https://docs.rs/curve25519-dalek/latest/curve25519-dalek/backend/serial/curve_models/index.html
 [bbjlp08]: https://eprint.iacr.org/2008/013
 [cmo98]: https://link.springer.com/content/pdf/10.1007%2F3-540-49649-1_6.pdf
 [intel]: https://software.intel.com/sites/default/files/managed/9e/bc/64-ia-32-architectures-optimization-manual.pdf

src/backend/mod.rs

@@ -9,7 +9,7 @@
 // - isis agora lovecruft <[email protected]>
 // - Henry de Valence <[email protected]>
 
-//! Pluggable implementations for different architectures.
+//! **INTERNALS:** Pluggable implementations for different architectures.
 //!
 //! The backend code is split into two parts: a serial backend,
 //! and a vector backend.
@@ -36,18 +36,5 @@
 
 pub mod serial;
 
-#[cfg(any(
-    all(
-        feature = "simd_backend",
-        any(target_feature = "avx2", target_feature = "avx512ifma")
-    ),
-    all(feature = "nightly", rustdoc)
-))]
-#[cfg_attr(
-    feature = "nightly",
-    doc(cfg(any(all(
-        feature = "simd_backend",
-        any(target_feature = "avx2", target_feature = "avx512ifma")
-    ))))
-)]
+#[cfg(any(feature = "simd_backend", docsrs))]
 pub mod vector;

src/backend/serial/curve_models/mod.rs

@@ -148,6 +148,7 @@ use crate::traits::ValidityCheck;
 ///
 /// More details on the relationships between the different curve models
 /// can be found in the module-level documentation.
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
 pub struct ProjectivePoint {
     pub X: FieldElement,
@@ -199,6 +200,7 @@ impl Zeroize for AffineNielsPoint {
 /// More details on the relationships between the different curve models
 /// can be found in the module-level documentation.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub struct ProjectiveNielsPoint {
     pub Y_plus_X: FieldElement,
     pub Y_minus_X: FieldElement,

src/backend/serial/mod.rs

@@ -11,11 +11,9 @@
 
 //! Serial implementations of field, scalar, point arithmetic.
 //!
-//! When the vector backend is disabled, the crate uses the
-//! mixed-model strategy for implementing point operations and scalar
-//! multiplication; see the [`curve_models`](self::curve_models) and
-//! [`scalar_mul`](self::scalar_mul) documentation for more
-//! information.
+//! When the vector backend is disabled, the crate uses the mixed-model strategy
+//! for implementing point operations and scalar multiplication; see the
+//! [`curve_models`] and [`scalar_mul`] documentation for more information.
 //!
 //! When the vector backend is enabled, the field and scalar
 //! implementations are still used for non-vectorized operations.

src/backend/serial/scalar_mul/mod.rs

@@ -17,8 +17,10 @@
 //! scalar multiplication implementations, since it only uses one
 //! curve model.
 
+#[allow(missing_docs)]
 pub mod variable_base;
 
+#[allow(missing_docs)]
 pub mod vartime_double_base;
 
 #[cfg(feature = "alloc")]

src/backend/serial/scalar_mul/pippenger.rs

@@ -61,7 +61,8 @@ use crate::prelude::*;
 /// This algorithm is adapted from section 4 of <https://eprint.iacr.org/2012/549.pdf>.
 pub struct Pippenger;
 
-#[cfg(any(feature = "alloc", feature = "std"))]
+#[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimeMultiscalarMul for Pippenger {
     type Point = EdwardsPoint;
 

src/backend/serial/scalar_mul/precomputed_straus.rs

@@ -25,6 +25,7 @@ use crate::window::{NafLookupTable5, NafLookupTable8};
 #[allow(unused_imports)]
 use crate::prelude::*;
 
+#[allow(missing_docs)]
 pub struct VartimePrecomputedStraus {
     static_lookup_tables: Vec<NafLookupTable8<AffineNielsPoint>>,
 }

src/backend/serial/u32/constants.rs

@@ -122,14 +122,14 @@ pub const ED25519_BASEPOINT_POINT: EdwardsPoint = EdwardsPoint {
     ]),
 };
 
-/// The 8-torsion subgroup \\(\mathcal E [8]\\).
+/// The 8-torsion subgroup \\(\mathcal E \[8\]\\).
 ///
 /// In the case of Curve25519, it is cyclic; the \\(i\\)-th element of
 /// the array is \\([i]P\\), where \\(P\\) is a point of order \\(8\\)
-/// generating \\(\mathcal E[8]\\).
+/// generating \\(\mathcal E\[8\]\\).
 ///
-/// Thus \\(\mathcal E[4]\\) is the points indexed by `0,2,4,6`, and
-/// \\(\mathcal E[2]\\) is the points indexed by `0,4`.
+/// Thus \\(\mathcal E\[4\]\\) is the points indexed by `0,2,4,6`, and
+/// \\(\mathcal E\[2\]\\) is the points indexed by `0,4`.
 /// The Ed25519 basepoint has y = 4/5.  This is called `_POINT` to
 /// distinguish it from `_TABLE`, which should be used for scalar
 /// multiplication (it's much faster).

src/backend/serial/u64/constants.rs

@@ -167,14 +167,14 @@ pub const ED25519_BASEPOINT_POINT: EdwardsPoint = EdwardsPoint {
     ]),
 };
 
-/// The 8-torsion subgroup \\(\mathcal E [8]\\).
+/// The 8-torsion subgroup \\(\mathcal E \[8\]\\).
 ///
 /// In the case of Curve25519, it is cyclic; the \\(i\\)-th element of
-/// the array is \\([i]P\\), where \\(P\\) is a point of order \\(8\\)
-/// generating \\(\mathcal E[8]\\).
+/// the array is \\(\[i\]P\\), where \\(P\\) is a point of order \\(8\\)
+/// generating \\(\mathcal E\[8\]\\).
 ///
-/// Thus \\(\mathcal E[4]\\) is the points indexed by `0,2,4,6`, and
-/// \\(\mathcal E[2]\\) is the points indexed by `0,4`.
+/// Thus \\(\mathcal E\[4\]\\) is the points indexed by `0,2,4,6`, and
+/// \\(\mathcal E\[2\]\\) is the points indexed by `0,4`.
 pub const EIGHT_TORSION: [EdwardsPoint; 8] = EIGHT_TORSION_INNER_DOC_HIDDEN;
 
 /// Inner item used to hide limb constants from cargo doc output.

src/backend/vector/ifma/mod.rs

@@ -9,8 +9,10 @@
 
 #![doc = include_str!("../../../../docs/ifma-notes.md")]
 
+#[allow(missing_docs)]
 pub mod field;
 
+#[allow(missing_docs)]
 pub mod edwards;
 
 pub mod constants;

src/backend/vector/mod.rs

@@ -11,29 +11,29 @@
 
 #![doc = include_str!("../../../docs/parallel-formulas.md")]
 
-#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", rustdoc)))]
+#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", docsrs)))]
 compile_error!("simd_backend selected without target_feature=+avx2 or +avx512ifma");
 
 #[cfg(any(
     all(target_feature = "avx2", not(target_feature = "avx512ifma")),
-    rustdoc
+    all(docsrs, target_arch = "x86_64")
 ))]
-#[doc(cfg(all(target_feature = "avx2", not(target_feature = "avx512ifma"))))]
 pub mod avx2;
 #[cfg(any(
     all(target_feature = "avx2", not(target_feature = "avx512ifma")),
-    rustdoc
+    all(docsrs, target_arch = "x86_64")
 ))]
 pub(crate) use self::avx2::{
     constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint,
 };
 
-#[cfg(any(target_feature = "avx512ifma", rustdoc))]
-#[doc(cfg(target_feature = "avx512ifma"))]
+#[cfg(any(target_feature = "avx512ifma", all(docsrs, target_arch = "x86_64")))]
 pub mod ifma;
 #[cfg(target_feature = "avx512ifma")]
 pub(crate) use self::ifma::{
     constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint,
 };
 
+#[cfg(any(target_feature = "avx2", target_feature = "avx512ifma", all(docsrs, target_arch = "x86_64")))]
+#[allow(missing_docs)]
 pub mod scalar_mul;

src/backend/vector/scalar_mul/mod.rs

@@ -14,10 +14,13 @@ pub mod variable_base;
 pub mod vartime_double_base;
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 pub mod straus;
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 pub mod precomputed_straus;
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 pub mod pippenger;

src/backend/vector/scalar_mul/pippenger.rs

@@ -24,7 +24,8 @@ use crate::prelude::*;
 /// See the documentation in the serial `scalar_mul::pippenger` module for details.
 pub struct Pippenger;
 
-#[cfg(any(feature = "alloc", feature = "std"))]
+#[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimeMultiscalarMul for Pippenger {
     type Point = EdwardsPoint;