Merge branch 'feature/sasl-feature-markers-on-docsrs' into 'main'

Draft: Nicer documentation

See merge request xmpp-rs/xmpp-rs!316

.gitlab-ci.yml

@@ -41,7 +41,7 @@ variables:
   stage: test
   script:
     - echo "Building docs to CI_DOC_TARGET=$CI_DOC_TARGET"
-    - cargo +nightly doc --no-deps -Zrustdoc-map
+    - RUSTDOCFLAGS="--cfg docsrs" RUSTFLAGS="--cfg xmpprs_doc_build" cargo +nightly doc --no-deps -Zrustdoc-map --all-features
     - apt install -y rsync openssh-client
     - mkdir -p $HOME/.ssh
     - echo -e "Host docs\n\tHostname docs.xmpp.rs\n\tPort 1312\n\tUser xmpp-rs\n\tStrictHostKeyChecking no" > $HOME/.ssh/config

sasl/Cargo.toml

@@ -26,3 +26,7 @@ sha-1 = { version = "0.10", optional = true }
 sha2 = { version = "0.10", optional = true }
 hmac = { version = "0.12", optional = true }
 pbkdf2 = { version = "0.12", default-features = false, optional = true }
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

sasl/src/client/mechanisms/mod.rs

@@ -10,4 +10,5 @@ pub use self::anonymous::Anonymous;
 pub use self::plain::Plain;
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 pub use self::scram::Scram;

sasl/src/client/mod.rs

@@ -34,6 +34,7 @@ pub enum MechanismError {
 }
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 impl From<DeriveError> for MechanismError {
     fn from(err: DeriveError) -> MechanismError {
         MechanismError::DeriveError(err)
@@ -41,6 +42,7 @@ impl From<DeriveError> for MechanismError {
 }
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 impl From<InvalidLength> for MechanismError {
     fn from(err: InvalidLength) -> MechanismError {
         MechanismError::InvalidKeyLength(err)

sasl/src/common/mod.rs

@@ -2,6 +2,7 @@ use std::collections::HashMap;
 use std::string::FromUtf8Error;
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 pub mod scram;
 
 #[derive(Clone, Debug, PartialEq, Eq)]

sasl/src/error.rs

@@ -5,6 +5,7 @@ use getrandom::Error as RngError;
 #[derive(Debug)]
 pub enum Error {
     #[cfg(feature = "scram")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
     /// An error while initializing the Rng.
     RngError(RngError),
     /// An error in a SASL mechanism.
@@ -12,6 +13,7 @@ pub enum Error {
 }
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 impl From<RngError> for Error {
     fn from(err: RngError) -> Error {
         Error::RngError(err)

sasl/src/lib.rs

@@ -1,4 +1,5 @@
 //#![deny(missing_docs)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 //! This crate provides a framework for SASL authentication and a few authentication mechanisms.
 //!

sasl/src/secret.rs

@@ -23,6 +23,7 @@ pub struct Pbkdf2Sha1 {
 
 impl Pbkdf2Sha1 {
     #[cfg(feature = "scram")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
     pub fn derive(password: &str, salt: &[u8], iterations: u32) -> Result<Pbkdf2Sha1, DeriveError> {
         use crate::common::scram::{ScramProvider, Sha1};
         use crate::common::Password;
@@ -58,6 +59,7 @@ pub struct Pbkdf2Sha256 {
 
 impl Pbkdf2Sha256 {
     #[cfg(feature = "scram")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
     pub fn derive(
         password: &str,
         salt: &[u8],

sasl/src/server/mechanisms/mod.rs

@@ -5,7 +5,9 @@ mod plain;
 mod scram;
 
 #[cfg(feature = "anonymous")]
+#[cfg_attr(docsrs, doc(cfg(feature = "anonymous")))]
 pub use self::anonymous::Anonymous;
 pub use self::plain::Plain;
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 pub use self::scram::Scram;

sasl/src/server/mod.rs

@@ -36,6 +36,7 @@ pub trait Validator<S: Secret> {
 pub enum ProviderError {
     AuthenticationFailed,
     #[cfg(feature = "scram")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
     DeriveError(DeriveError),
 }
 
@@ -65,8 +66,10 @@ pub enum MechanismError {
 
     CannotDecodeResponse,
     #[cfg(feature = "scram")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
     InvalidKeyLength(hmac::digest::InvalidLength),
     #[cfg(any(feature = "scram", feature = "anonymous"))]
+    #[cfg_attr(docsrs, doc(cfg(any(feature = "scram", feature = "anonymous"))))]
     RandomFailure(getrandom::Error),
     NoProof,
     CannotDecodeProof,
@@ -75,6 +78,7 @@ pub enum MechanismError {
 }
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 impl From<DeriveError> for ProviderError {
     fn from(err: DeriveError) -> ProviderError {
         ProviderError::DeriveError(err)
@@ -100,6 +104,7 @@ impl From<ValidatorError> for MechanismError {
 }
 
 #[cfg(feature = "scram")]
+#[cfg_attr(docsrs, doc(cfg(feature = "scram")))]
 impl From<hmac::digest::InvalidLength> for MechanismError {
     fn from(err: hmac::digest::InvalidLength) -> MechanismError {
         MechanismError::InvalidKeyLength(err)
@@ -107,6 +112,7 @@ impl From<hmac::digest::InvalidLength> for MechanismError {
 }
 
 #[cfg(any(feature = "scram", feature = "anonymous"))]
+#[cfg_attr(docsrs, doc(cfg(any(feature = "scram", feature = "anonymous"))))]
 impl From<getrandom::Error> for MechanismError {
     fn from(err: getrandom::Error) -> MechanismError {
         MechanismError::RandomFailure(err)

tokio-xmpp/src/lib.rs

@@ -2,7 +2,12 @@
 
 #![deny(unsafe_code, missing_docs, bare_trait_objects)]
 
-#[cfg(all(feature = "tls-native", feature = "tls-rust"))]
+#[cfg(all(
+    not(xmpprs_doc_build),
+    not(doc),
+    feature = "tls-native",
+    feature = "tls-rust"
+))]
 compile_error!("Both tls-native and tls-rust features can't be enabled at the same time.");
 
 #[cfg(all(

tokio-xmpp/src/starttls/mod.rs

@@ -114,7 +114,7 @@ impl ServerConnector for ServerConfig {
 async fn get_tls_stream<S: AsyncRead + AsyncWrite + Unpin>(
     xmpp_stream: XMPPStream<S>,
 ) -> Result<TlsStream<S>, Error> {
-    let domain = xmpp_stream.jid.domain_str().to_owned();
+    let domain = xmpp_stream.jid.domain().to_owned();
     let stream = xmpp_stream.into_inner();
     let tls_stream = TlsConnector::from(NativeTlsConnector::builder().build().unwrap())
         .connect(&domain, stream)