Merge pull request #439 from pinkforest/docs-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", "docs/assets/rustdoc-include-katex-header.html", "--cfg", "docsrs"]
-# rustdoc-args = ["--html-in-header", ".cargo/registry/src/github.com-1ecc6299db9ec823/curve25519-dalek-0.13.2/rustdoc-include-katex-header.html"]
+features = ["serde", "simd_backend"]
-features = ["nightly", "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 +nightly 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 +nightly 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%"
+ width="300px"
- align="right"
+ 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
@@ -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 <isis@patternsinthevoid.net>
 // - Henry de Valence <hdevalence@hdevalence.ca>
 
-//! 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(
+#[cfg(any(feature = "simd_backend", docsrs))]
-    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")
-    ))))
-)]
 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/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/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))]
+#[cfg(any(target_feature = "avx512ifma", all(docsrs, target_arch = "x86_64")))]
-#[doc(cfg(target_feature = "avx512ifma"))]
 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;
 

src/edwards.rs

@@ -85,7 +85,7 @@
 //! successful decompression of a compressed point, or else by
 //! operations on other (valid) `EdwardsPoint`s.
 //!
-//! [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
 
 // We allow non snake_case names because coordinates in projective space are
 // traditionally denoted by the capitalisation of their respective
@@ -134,9 +134,9 @@ use crate::traits::BasepointTable;
 use crate::traits::ValidityCheck;
 use crate::traits::{Identity, IsIdentity};
 
-#[cfg(any(feature = "alloc", feature = "std"))]
+#[cfg(feature = "alloc")]
 use crate::traits::MultiscalarMul;
-#[cfg(any(feature = "alloc", feature = "std"))]
+#[cfg(feature = "alloc")]
 use crate::traits::{VartimeMultiscalarMul, VartimePrecomputedMultiscalarMul};
 
 #[cfg(not(all(
@@ -707,6 +707,7 @@ impl<'a, 'b> Mul<&'b EdwardsPoint> for &'a Scalar {
 // forward to a specific backend implementation.
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl MultiscalarMul for EdwardsPoint {
     type Point = EdwardsPoint;
 
@@ -739,6 +740,7 @@ impl MultiscalarMul for EdwardsPoint {
 }
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimeMultiscalarMul for EdwardsPoint {
     type Point = EdwardsPoint;
 
@@ -778,9 +780,11 @@ impl VartimeMultiscalarMul for EdwardsPoint {
 // decouple stability of the inner type from the stability of the
 // outer type.
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 pub struct VartimeEdwardsPrecomputation(scalar_mul::precomputed_straus::VartimePrecomputedStraus);
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimePrecomputedMultiscalarMul for VartimeEdwardsPrecomputation {
     type Point = EdwardsPoint;
 

src/field.rs

@@ -167,6 +167,7 @@ impl FieldElement {
     ///
     /// When an input `FieldElement` is zero, its value is unchanged.
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
     pub fn batch_invert(inputs: &mut [FieldElement]) {
         // Montgomery’s Trick and Fast Implementation of Masked AES
         // Genelle, Prouff and Quisquater

src/lib.rs

@@ -10,16 +10,16 @@
 // - Henry de Valence <hdevalence@hdevalence.ca>
 
 #![no_std]
-#![cfg_attr(feature = "nightly", feature(test))]
-#![cfg_attr(feature = "nightly", feature(doc_cfg))]
 #![cfg_attr(feature = "simd_backend", feature(stdsimd))]
-
+#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg, doc_cfg_hide))]
+#![cfg_attr(docsrs, doc(cfg_hide(docsrs)))]
 //------------------------------------------------------------------------
 // Documentation:
 //------------------------------------------------------------------------
-
 #![deny(missing_docs)]
-#![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
+#![doc(
+    html_logo_url = "https://cdn.jsdelivr.net/gh/dalek-cryptography/curve25519-dalek/docs/assets/dalek-logo-clear.png"
+)]
 #![doc(html_root_url = "https://docs.rs/curve25519-dalek/4.0.0-pre.2")]
 #![doc = include_str!("../README.md")]
 
@@ -72,9 +72,13 @@ pub mod traits;
 pub(crate) mod field;
 
 // Arithmetic backends (using u32, u64, etc) live here
+#[cfg(docsrs)]
+pub mod backend;
+#[cfg(not(docsrs))]
 pub(crate) mod backend;
 
 // Crate-local prelude (for alloc-dependent features like `Vec`)
+
 pub(crate) mod prelude;
 
 // Generic code for window lookups

src/ristretto.rs

@@ -190,7 +190,7 @@ use crate::scalar::Scalar;
 
 use crate::traits::BasepointTable;
 use crate::traits::Identity;
-#[cfg(any(feature = "alloc", feature = "std"))]
+#[cfg(feature = "alloc")]
 use crate::traits::{MultiscalarMul, VartimeMultiscalarMul, VartimePrecomputedMultiscalarMul};
 
 #[cfg(not(all(
@@ -520,6 +520,7 @@ impl RistrettoPoint {
     /// # }
     /// ```
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
     pub fn double_and_compress_batch<'a, I>(points: I) -> Vec<CompressedRistretto>
     where
         I: IntoIterator<Item = &'a RistrettoPoint>,
@@ -922,6 +923,7 @@ define_mul_variants!(LHS = Scalar, RHS = RistrettoPoint, Output = RistrettoPoint
 // forward to the EdwardsPoint implementations.
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl MultiscalarMul for RistrettoPoint {
     type Point = RistrettoPoint;
 
@@ -938,6 +940,7 @@ impl MultiscalarMul for RistrettoPoint {
 }
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimeMultiscalarMul for RistrettoPoint {
     type Point = RistrettoPoint;
 
@@ -958,9 +961,11 @@ impl VartimeMultiscalarMul for RistrettoPoint {
 // decouple stability of the inner type from the stability of the
 // outer type.
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 pub struct VartimeRistrettoPrecomputation(scalar_mul::precomputed_straus::VartimePrecomputedStraus);
 
 #[cfg(feature = "alloc")]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
 impl VartimePrecomputedMultiscalarMul for VartimeRistrettoPrecomputation {
     type Point = RistrettoPoint;
 

src/scalar.rs

@@ -173,6 +173,10 @@ cfg_if! {
         /// This is a type alias for one of the scalar types in the `backend`
         /// module.
         #[cfg(not(target_pointer_width = "64"))]
+        #[cfg_attr(
+            docsrs,
+            doc(cfg(all(feature = "fiat_backend", not(target_pointer_width = "64"))))
+        )]
         type UnpackedScalar = backend::serial::fiat_u32::scalar::Scalar29;
 
         /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed.
@@ -180,18 +184,24 @@ cfg_if! {
         /// This is a type alias for one of the scalar types in the `backend`
         /// module.
         #[cfg(target_pointer_width = "64")]
+        #[cfg_attr(
+            docsrs,
+            doc(cfg(all(feature = "fiat_backend", target_pointer_width = "64")))
+        )]
         type UnpackedScalar = backend::serial::fiat_u64::scalar::Scalar52;
     } else if #[cfg(target_pointer_width = "64")] {
         /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed.
         ///
         /// This is a type alias for one of the scalar types in the `backend`
         /// module.
+        #[cfg_attr(docsrs, doc(cfg(target_pointer_width = "64")))]
         type UnpackedScalar = backend::serial::u64::scalar::Scalar52;
     } else {
         /// An `UnpackedScalar` represents an element of the field GF(l), optimized for speed.
         ///
         /// This is a type alias for one of the scalar types in the `backend`
         /// module.
+        #[cfg_attr(docsrs, doc(cfg(not(target_pointer_width = "64"))))]
         type UnpackedScalar = backend::serial::u32::scalar::Scalar29;
     }
 }
@@ -401,6 +411,7 @@ use serde::de::Visitor;
 use serde::{self, Deserialize, Deserializer, Serialize, Serializer};
 
 #[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
 impl Serialize for Scalar {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
@@ -416,6 +427,7 @@ impl Serialize for Scalar {
 }
 
 #[cfg(feature = "serde")]
+#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
 impl<'de> Deserialize<'de> for Scalar {
     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
     where
@@ -773,6 +785,7 @@ impl Scalar {
     /// # }
     /// ```
     #[cfg(feature = "alloc")]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
     pub fn batch_invert(inputs: &mut [Scalar]) -> Scalar {
         // This code is essentially identical to the FieldElement
         // implementation, and is documented there.  Unfortunately,