docs: fix doc links

.github/workflows/lint.yml

@@ -52,6 +52,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
   docs:
+    name: Docs
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

README.md

@@ -16,9 +16,9 @@ See [`http_challenge`] and [`dns_challenge`].
 
 When creating a new order, it's possible to provide multiple alt-names that will also be part of the certificate. The ACME API requires you to prove ownership of each such domain. See [`authorizations`].
 
-[`http_challenge`]: https://docs.rs/acme-lite/0.12/acme_lite/order/struct.Auth.html#method.http_challenge
-[`dns_challenge`]: https://docs.rs/acme-lite/0.12/acme_lite/order/struct.Auth.html#method.dns_challenge
-[`authorizations`]: https://docs.rs/acme-lite/0.12/acme_lite/order/struct.NewOrder.html#method.authorizations
+[`http_challenge`]: https://docs.rs/acme-lite/0.0.2/acme_lite/order/struct.Auth.html#method.http_challenge
+[`dns_challenge`]: https://docs.rs/acme-lite/0.0.2/acme_lite/order/struct.Auth.html#method.dns_challenge
+[`authorizations`]: https://docs.rs/acme-lite/0.0.2/acme_lite/order/struct.NewOrder.html#method.authorizations
 
 ## Rate limits
 

src/acc/mod.rs

@@ -24,18 +24,16 @@ pub(crate) struct AccountInner {
 
 /// Account with an ACME provider.
 ///
-/// Accounts are created using [`Directory::account`] and consist of a contact
-/// email address and a private key for signing requests to the ACME API.
+/// Accounts are created using [`Directory::register_account()`] and consist of a contact email
+/// address and a private key for signing requests to the ACME API.
 ///
-/// acme-lib uses elliptic curve P-256 for accessing the account. This
-/// does not affect which key algorithms that can be used for the
-/// issued certificates.
+/// This library uses elliptic curve P-256 for accessing the account. This does not affect which key
+/// algorithms that can be used for the issued certificates.
 ///
-/// The advantage of using elliptic curve cryptography is that the signed
-/// requests against the ACME lib are kept small and that the public key
-/// can be derived from the private.
+/// The advantages of using elliptic curve cryptography are that the signed requests against the
+/// ACME lib are small and that the public key can be derived from the private key.
 ///
-/// [`Directory::account`]: struct.Directory.html#method.account
+/// [`Directory::register_account()`]: crate::Directory::register_account()
 #[derive(Clone)]
 pub struct Account {
     inner: Arc<AccountInner>,
@@ -113,13 +111,13 @@ impl Account {
         // convert to base64url of the DER (which is not PEM).
         let certificate = BASE64_URL_SAFE_NO_PAD.encode(cert.certificate_der()?);
 
-        let revoc = ApiRevocation {
+        let revocation = ApiRevocation {
             certificate,
             reason: reason as usize,
         };
 
         let url = &self.inner.api_directory.revoke_cert;
-        self.inner.transport.call(url, &revoc).await?;
+        self.inner.transport.call(url, &revocation).await?;
 
         Ok(())
     }

src/dir.rs

@@ -139,51 +139,4 @@ mod tests {
             .await
             .unwrap();
     }
-
-    // #[test]
-    // fn test_the_whole_hog() {
-    //     std::env::set_var("RUST_LOG", "acme_lite=trace");
-    //     let _ = env_logger::try_init();
-
-    //     use crate::cert::create_p384_key;
-
-    //     let url = DirectoryUrl::LetsEncryptStaging;
-    //     let persist = FilePersist::new(".");
-    //     let dir = Directory::from_url(persist, url)?;
-    //     let acc = dir.account("foo@bar.com")?;
-
-    //     let mut ord = acc.new_order("myspecialsite.com", &[])?;
-
-    //     let ord = loop {
-    //         if let Some(ord) = ord.confirm_validations() {
-    //             break ord;
-    //         }
-
-    //         let auths = ord.authorizations()?;
-    //         let chall = auths[0].dns_challenge();
-
-    //         info!("Proof: {}", chall.dns_proof());
-
-    //         use std::thread;
-    //         use std::time::Duration;
-    //         tokio::time::sleep(Duration::from_millis(60_000)).await;
-
-    //         chall.validate(5000)?;
-
-    //         ord.refresh()?;
-    //     };
-
-    //     let (pkey_pri, pkey_pub) = create_p384_key();
-
-    //     let ord = ord.finalize_signing_key(pkey_pri, pkey_pub, 5000)?;
-
-    //     let cert = ord.download_and_save_cert()?;
-    //     println!(
-    //         "{}{}{}",
-    //         cert.private_key(),
-    //         cert.certificate(),
-    //         cert.valid_days_left()
-    //     );
-    //     Ok(())
-    // }
 }

src/lib.rs

@@ -120,9 +120,9 @@ When creating a new order, it's possible to provide multiple alt-names that will
 be part of the certificate. The ACME API requires you to prove ownership of each such
 domain. See [`authorizations`].
 
-[`http_challenge`]: https://docs.rs/acme-lite/0.1/acme_lite/order/struct.Auth.html#method.http_challenge
-[`dns_challenge`]: https://docs.rs/acme-lite/0.1/acme_lite/order/struct.Auth.html#method.dns_challenge
-[`authorizations`]: https://docs.rs/acme-lite/0.1/acme_lite/order/struct.NewOrder.html#method.authorizations
+[`http_challenge`]: order::Auth::http_challenge()
+[`dns_challenge`]: order::Auth::dns_challenge()
+[`authorizations`]: order::NewOrder::authorizations()
 
 ## Rate limits
 

src/order/auth.rs

@@ -99,7 +99,7 @@ impl Auth {
     /// _acme-challenge.<domain-to-be-proven>.  TXT  <proof>
     /// ```
     ///
-    /// The <proof> contains the signed token proving this account update it.
+    /// The `<proof>` contains the signed token proving this account update it.
     ///
     /// ```no_run
     /// use std::time::Duration;
@@ -155,8 +155,6 @@ pub struct Dns;
 pub struct TlsAlpn;
 
 /// A DNS, HTTP, or TLS-ALPN challenge as obtained from the [`Auth`].
-///
-/// [`Auth`]: struct.Auth.html
 pub struct Challenge<A> {
     inner: Arc<AccountInner>,
     api_challenge: ApiChallenge,
@@ -165,8 +163,9 @@ pub struct Challenge<A> {
 }
 
 impl Challenge<Http> {
-    /// The `token` is a unique identifier of the challenge. It is the file name in the
-    /// http challenge like so:
+    /// Returns the token, a unique identifier of the challenge.
+    ///
+    /// This is used as the file name in the HTTP challenge like so:
     ///
     /// ```text
     /// http://<domain-to-be-proven>/.well-known/acme-challenge/<token>
@@ -175,7 +174,9 @@ impl Challenge<Http> {
         &self.api_challenge.token
     }
 
-    /// The `proof` is some text content that is placed in the file named by `token`.
+    /// Returns the proof content for HTTP validation.
+    ///
+    /// Proof is typically placed in a text file that is served as the file named by `token`.
     pub fn http_proof(&self) -> eyre::Result<String> {
         let acme_key = self.inner.transport.acme_key();
         let proof = key_authorization(&self.api_challenge.token, acme_key, false)?;
@@ -184,9 +185,11 @@ impl Challenge<Http> {
 }
 
 impl Challenge<Dns> {
-    /// The `proof` is the `TXT` record placed under:
+    /// Returns the proof content for DNS validation.
     ///
-    /// ```text
+    /// Proof is to be placed in a DNS TXT record like so:
+    ///
+    /// ```plain
     /// _acme-challenge.<domain-to-be-proven>.  TXT  <proof>
     /// ```
     pub fn dns_proof(&self) -> eyre::Result<String> {
@@ -197,12 +200,16 @@ impl Challenge<Dns> {
 }
 
 impl Challenge<TlsAlpn> {
-    /// The `proof` is the contents of the ACME extension to be placed in the
-    /// certificate used for validation.
+    /// Returns the proof content for TLS-ALPN validation.
+    ///
+    /// Proof is to be placed in the certificate used for validation.
     pub fn tls_alpn_proof(&self) -> eyre::Result<[u8; 32]> {
         let acme_key = self.inner.transport.acme_key();
         let proof = key_authorization(&self.api_challenge.token, acme_key, false)?;
-        Ok(Sha256::digest(proof).try_into().unwrap())
+
+        Ok(Sha256::digest(proof)
+            .try_into()
+            .expect("SHA-256 should produce a 32-byte output"))
     }
 }
 

src/order/mod.rs

@@ -10,13 +10,6 @@
 //!    * [`NewOrder`] -> [`CsrOrder`] -> [`CertOrder`]
 //!
 //! \* Possibly multiple auths.
-//!
-//! [`ApiOrder`]: ../api/struct.ApiOrder.html
-//! [`NewOrder`]: struct.NewOrder.html
-//! [`Auth`]: struct.Auth.html
-//! [`Challenge`]: struct.Challenge.html
-//! [`CsrOrder`]: struct.CsrOrder.html
-//! [`CertOrder`]: struct.CertOrder.html
 
 use std::{sync::Arc, time::Duration};
 
@@ -87,7 +80,7 @@ async fn api_order_of(res: reqwest::Response, want_status: &str) -> eyre::Result
     Ok(api_order)
 }
 
-/// A new order created by [`Account::new_order`].
+/// A new order created by [`Account::new_order()`].
 ///
 /// An order is created using one or many domains (a primary `CN` and possible multiple
 /// alt names). All domains in the order must have authorizations ([confirmed ownership])
@@ -100,7 +93,7 @@ async fn api_order_of(res: reqwest::Response, want_status: &str) -> eyre::Result
 /// means you might not need to prove the ownership every time. Use appropriate methods to
 /// first check whether you really need to handle authorizations.
 ///
-/// [`Account::new_order`]: ../struct.Account.html#method.new_order
+/// [`Account::new_order()`]: crate::Account::new_order()
 /// [confirmed ownership]: ../index.html#domain-ownership
 /// [CSR]: https://en.wikipedia.org/wiki/Certificate_signing_request
 pub struct NewOrder {
@@ -112,20 +105,20 @@ impl NewOrder {
     ///
     /// This doesn't do any calls against the API. You must manually call [`refresh`].
     ///
-    /// In ACME API terms, the order can either be `ready` or `valid`, which both would
-    /// mean we have passed the authorization stage.
+    /// In ACME API terms, the order can either be `ready` or `valid`, which both would mean we have
+    /// passed the authorization stage.
     ///
-    /// [`refresh`]: struct.NewOrder.html#method.refresh
+    /// [`refresh`]: Self::refresh
     pub fn is_validated(&self) -> bool {
         self.order.api_order.is_status_ready() || self.order.api_order.is_status_valid()
     }
 
-    /// If the order [`is_validated`] progress it to a [`CsrOrder`].
+    /// If the order [is validated], progress it to a [`CsrOrder`].
     ///
     /// This doesn't do any calls against the API. You must manually call [`refresh`].
     ///
-    /// [`is_validated`]: struct.NewOrder.html#method.is_validated
-    /// [`CsrOrder`]: struct.CsrOrder.html
+    /// [is validated]: Self::is_validated
+    /// [`refresh`]: Self::refresh
     pub fn confirm_validations(&self) -> Option<CsrOrder> {
         if self.is_validated() {
             Some(CsrOrder {
@@ -211,7 +204,7 @@ impl CsrOrder {
     ///
     /// This is a convenience wrapper that in turn calls the lower level [`finalize_signing_key`].
     ///
-    /// [`finalize_signing_key`]: struct.CsrOrder.html#method.finalize_signing_key
+    /// [`finalize_signing_key`]: Self::finalize_signing_key
     pub async fn finalize(self, private_key_pem: &str, delay: Duration) -> eyre::Result<CertOrder> {
         let signing_key =
             SigningKey::from_pkcs8_pem(private_key_pem).context("Error reading private key PEM")?;