RUST-1512 Better links for action return types (#1054)

Author: abr-egn

action_macro/Cargo.toml

@@ -9,7 +9,7 @@ license = "Apache-2.0"
 [dependencies]
 proc-macro2 = "1.0.78"
 quote = "1.0.35"
-syn = { version = "2.0.52", features = ["full", "parsing", "proc-macro"] }
+syn = { version = "2.0.52", features = ["full", "parsing", "proc-macro", "extra-traits"] }
 
 [lib]
 proc-macro = true

action_macro/src/lib.rs

@@ -1,6 +1,6 @@
 extern crate proc_macro;
 
-use quote::quote;
+use quote::{quote, ToTokens};
 use syn::{
     braced,
     parenthesized,
@@ -11,9 +11,13 @@ use syn::{
     spanned::Spanned,
     Block,
     Error,
+    Expr,
     Generics,
     Ident,
+    ImplItemFn,
     Lifetime,
+    Lit,
+    Meta,
     Token,
     Type,
 };
@@ -218,3 +222,106 @@ fn parse_name(input: ParseStream, name: &str) -> syn::Result<()> {
     }
     Ok(())
 }
+
+/// Enables rustdoc links to types that link individually to each type
+/// component.
+#[proc_macro_attribute]
+pub fn deeplink(
+    _attr: proc_macro::TokenStream,
+    item: proc_macro::TokenStream,
+) -> proc_macro::TokenStream {
+    let mut impl_fn = parse_macro_input!(item as ImplItemFn);
+
+    for attr in &mut impl_fn.attrs {
+        // Skip non-`doc` attrs
+        if attr.path() != &parse_quote! { doc } {
+            continue;
+        }
+        // Get the string literal value from #[doc = "lit"]
+        let mut text = match &mut attr.meta {
+            Meta::NameValue(nv) => match &mut nv.value {
+                Expr::Lit(el) => match &mut el.lit {
+                    Lit::Str(ls) => ls.value(),
+                    _ => continue,
+                },
+                _ => continue,
+            },
+            _ => continue,
+        };
+        // Process substrings delimited by "d[...]"
+        while let Some(ix) = text.find("d[") {
+            let pre = &text[..ix];
+            let rest = &text[ix + 2..];
+            let end = match rest.find(']') {
+                Some(v) => v,
+                None => {
+                    return Error::new(attr.span(), "unterminated d[")
+                        .into_compile_error()
+                        .into()
+                }
+            };
+            let body = &rest[..end];
+            let post = &rest[end + 1..];
+            // Strip inner backticks, if any
+            let (fixed, body) = if body.starts_with('`') && body.ends_with('`') {
+                (
+                    true,
+                    body.strip_prefix('`').unwrap().strip_suffix('`').unwrap(),
+                )
+            } else {
+                (false, body)
+            };
+            // Build new string
+            let mut new_text = pre.to_owned();
+            if fixed {
+                new_text.push_str("<code>");
+            }
+            new_text.push_str(&text_link(body));
+            if fixed {
+                new_text.push_str("</code>");
+            }
+            new_text.push_str(post);
+            text = new_text;
+        }
+        *attr = parse_quote! { #[doc = #text] };
+    }
+
+    impl_fn.into_token_stream().into()
+}
+
+fn text_link(text: &str) -> String {
+    // Break into segments delimited by '<' or '>'
+    let segments = text.split_inclusive(&['<', '>'])
+        // Put each delimiter in its own segment
+        .flat_map(|s| {
+            if s == "<" || s == ">" {
+                vec![s]
+            } else if let Some(sub) = s.strip_suffix(&['<', '>']) {
+                vec![sub, &s[sub.len()..]]
+            } else {
+                vec![s]
+            }
+        });
+
+    // Build output
+    let mut out = vec![];
+    for segment in segments {
+        match segment {
+            // Escape angle brackets
+            "<" => out.push("&lt;"),
+            ">" => out.push("&gt;"),
+            // Don't link unit
+            "()" => out.push("()"),
+            // Link to types
+            _ => {
+                // Use the short name
+                let short = segment
+                    .rsplit_once("::")
+                    .map(|(_, short)| short)
+                    .unwrap_or(segment);
+                out.extend(["[", short, "](", segment, ")"]);
+            }
+        }
+    }
+    out.concat()
+}

src/action.rs

@@ -143,7 +143,7 @@ pub trait Action: private::Sealed + IntoFuture {
     }
 }
 
-pub(crate) use action_macro::action_impl;
+pub(crate) use action_macro::{action_impl, deeplink};
 
 use crate::Collection;
 

src/action/aggregate.rs

@@ -16,16 +16,17 @@ use crate::{
     SessionCursor,
 };
 
-use super::{action_impl, option_setters, CollRef, ExplicitSession, ImplicitSession};
+use super::{action_impl, deeplink, option_setters, CollRef, ExplicitSession, ImplicitSession};
 
 impl Database {
     /// Runs an aggregation operation.
     ///
     /// See the documentation [here](https://www.mongodb.com/docs/manual/aggregation/) for more
     /// information on aggregations.
     ///
-    /// `await` will return `Result<`[`Cursor`]`<Document>>` or `Result<SessionCursor<Document>>` if
+    /// `await` will return d[`Result<Cursor<Document>>`] or d[`Result<SessionCursor<Document>>`] if
     /// a `ClientSession` is provided.
+    #[deeplink]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         Aggregate {
             target: AggregateTargetRef::Database(self),
@@ -45,8 +46,9 @@ where
     /// See the documentation [here](https://www.mongodb.com/docs/manual/aggregation/) for more
     /// information on aggregations.
     ///
-    /// `await` will return `Result<Cursor<Document>>` or `Result<SessionCursor<Document>>` if
-    /// a `ClientSession` is provided.
+    /// `await` will return d[`Result<Cursor<Document>>`] or d[`Result<SessionCursor<Document>>`] if
+    /// a [`ClientSession`] is provided.
+    #[deeplink]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         Aggregate {
             target: AggregateTargetRef::Collection(CollRef::new(self)),
@@ -64,8 +66,9 @@ impl crate::sync::Database {
     /// See the documentation [here](https://www.mongodb.com/docs/manual/aggregation/) for more
     /// information on aggregations.
     ///
-    /// [`run`](Aggregate::run) will return `Result<`[`Cursor`]`<Document>>` or
-    /// `Result<SessionCursor<Document>>` if a `ClientSession` is provided.
+    /// [`run`](Aggregate::run) will return d[`Result<crate::sync::Cursor<Document>>`] or
+    /// d[`Result<crate::sync::SessionCursor<Document>>`] if a [`ClientSession`] is provided.
+    #[deeplink]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         self.async_database.aggregate(pipeline)
     }
@@ -81,14 +84,15 @@ where
     /// See the documentation [here](https://www.mongodb.com/docs/manual/aggregation/) for more
     /// information on aggregations.
     ///
-    /// [`run`](Aggregate::run) will return `Result<Cursor<Document>>` or
-    /// `Result<SessionCursor<Document>>` if a `ClientSession` is provided.
+    /// [`run`](Aggregate::run) will return d[`Result<crate::sync::Cursor<Document>>`] or
+    /// d[`Result<crate::sync::SessionCursor<Document>>`] if a `ClientSession` is provided.
+    #[deeplink]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         self.async_collection.aggregate(pipeline)
     }
 }
 
-/// Run an aggregation operation.  Create by calling [`Database::aggregate`] or
+/// Run an aggregation operation.  Construct with [`Database::aggregate`] or
 /// [`Collection::aggregate`].
 #[must_use]
 pub struct Aggregate<'a, Session = ImplicitSession> {

src/action/count.rs

@@ -7,7 +7,7 @@ use crate::{
     Collection,
 };
 
-use super::{action_impl, option_setters, CollRef};
+use super::{action_impl, deeplink, option_setters, CollRef};
 
 impl<T> Collection<T>
 where
@@ -25,7 +25,8 @@ where
     /// For more information on the behavior of the `count` server command, see
     /// [Count: Behavior](https://www.mongodb.com/docs/manual/reference/command/count/#behavior).
     ///
-    /// `await` will return `Result<u64>`.
+    /// `await` will return d[`Result<u64>`].
+    #[deeplink]
     pub fn estimated_document_count(&self) -> EstimatedDocumentCount {
         EstimatedDocumentCount {
             cr: CollRef::new(self),
@@ -37,7 +38,8 @@ where
     ///
     /// Note that this method returns an accurate count.
     ///
-    /// `await` will return `Result<u64>`.
+    /// `await` will return d[`Result<u64>`].
+    #[deeplink]
     pub fn count_documents(&self, filter: Document) -> CountDocuments {
         CountDocuments {
             cr: CollRef::new(self),
@@ -65,7 +67,8 @@ where
     /// For more information on the behavior of the `count` server command, see
     /// [Count: Behavior](https://www.mongodb.com/docs/manual/reference/command/count/#behavior).
     ///
-    /// [`run`](EstimatedDocumentCount::run) will return `Result<u64>`.
+    /// [`run`](EstimatedDocumentCount::run) will return d[`Result<u64>`].
+    #[deeplink]
     pub fn estimated_document_count(&self) -> EstimatedDocumentCount {
         self.async_collection.estimated_document_count()
     }
@@ -74,13 +77,14 @@ where
     ///
     /// Note that this method returns an accurate count.
     ///
-    /// [`run`](CountDocuments::run) will return `Result<u64>`.
+    /// [`run`](CountDocuments::run) will return d[`Result<u64>`].
+    #[deeplink]
     pub fn count_documents(&self, filter: Document) -> CountDocuments {
         self.async_collection.count_documents(filter)
     }
 }
 
-/// Gather an estimated document count.  Create by calling [`Collection::estimated_document_count`].
+/// Gather an estimated document count.  Construct with [`Collection::estimated_document_count`].
 #[must_use]
 pub struct EstimatedDocumentCount<'a> {
     cr: CollRef<'a>,
@@ -108,7 +112,7 @@ action_impl! {
     }
 }
 
-/// Get an accurate count of documents.  Create by calling [`Collection::count_documents`].
+/// Get an accurate count of documents.  Construct with [`Collection::count_documents`].
 #[must_use]
 pub struct CountDocuments<'a> {
     cr: CollRef<'a>,

src/action/create_collection.rs

@@ -2,15 +2,16 @@ use bson::Document;
 
 use crate::{options::CreateCollectionOptions, ClientSession, Database};
 
-use crate::action::option_setters;
+use crate::action::{deeplink, option_setters};
 
 impl Database {
     /// Creates a new collection in the database with the given `name`.
     ///
     /// Note that MongoDB creates collections implicitly when data is inserted, so this method is
     /// not needed if no special options are required.
     ///
-    /// `await` will return `Result<()>`.
+    /// `await` will return d[`Result<()>`].
+    #[deeplink]
     pub fn create_collection(&self, name: impl AsRef<str>) -> CreateCollection {
         CreateCollection {
             db: self,
@@ -28,13 +29,14 @@ impl crate::sync::Database {
     /// Note that MongoDB creates collections implicitly when data is inserted, so this method is
     /// not needed if no special options are required.
     ///
-    /// [`run`](CreateCollection::run) will return `Result<()>`.
+    /// [`run`](CreateCollection::run) will return d[`Result<()>`].
+    #[deeplink]
     pub fn create_collection(&self, name: impl AsRef<str>) -> CreateCollection {
         self.async_database.create_collection(name)
     }
 }
 
-/// Creates a new collection.  Create by calling [`Database::create_collection`].
+/// Creates a new collection.  Construct with [`Database::create_collection`].
 #[must_use]
 pub struct CreateCollection<'a> {
     pub(crate) db: &'a Database,

src/action/create_index.rs

@@ -13,15 +13,16 @@ use crate::{
     IndexModel,
 };
 
-use super::{action_impl, option_setters, CollRef, Multiple, Single};
+use super::{action_impl, deeplink, option_setters, CollRef, Multiple, Single};
 
 impl<T> Collection<T>
 where
     T: Send + Sync,
 {
     /// Creates the given index on this collection.
     ///
-    /// `await` will return `Result<CreateIndexResult>`.
+    /// `await` will return d[`Result<CreateIndexResult>`].
+    #[deeplink]
     pub fn create_index(&self, index: IndexModel) -> CreateIndex {
         CreateIndex {
             coll: CollRef::new(self),
@@ -34,7 +35,8 @@ where
 
     /// Creates the given indexes on this collection.
     ///
-    /// `await` will return `Result<CreateIndexesResult>`.
+    /// `await` will return d[`Result<CreateIndexesResult>`].
+    #[deeplink]
     pub fn create_indexes(
         &self,
         indexes: impl IntoIterator<Item = IndexModel>,
@@ -56,14 +58,16 @@ where
 {
     /// Creates the given index on this collection.
     ///
-    /// [`run`](CreateIndex::run) will return `Result<CreateIndexResult>`.
+    /// [`run`](CreateIndex::run) will return d[`Result<CreateIndexResult>`].
+    #[deeplink]
     pub fn create_index(&self, index: IndexModel) -> CreateIndex {
         self.async_collection.create_index(index)
     }
 
     /// Creates the given indexes on this collection.
     ///
-    /// [`run`](CreateIndex::run) will return `Result<CreateIndexesResult>`.
+    /// [`run`](CreateIndex::run) will return d[`Result<CreateIndexesResult>`].
+    #[deeplink]
     pub fn create_indexes(
         &self,
         indexes: impl IntoIterator<Item = IndexModel>,

src/action/csfle/create_data_key.rs

@@ -1,12 +1,13 @@
 use crate::client_encryption::{ClientEncryption, MasterKey};
 
-use super::super::option_setters;
+use super::super::{deeplink, option_setters};
 
 impl ClientEncryption {
     /// Creates a new key document and inserts into the key vault collection.
     ///
-    /// `await` will return `Result<Binary>` (subtype 0x04) with the _id of the created
+    /// `await` will return d[`Result<Binary>`] (subtype 0x04) with the _id of the created
     /// document as a UUID.
+    #[deeplink]
     pub fn create_data_key(&self, master_key: MasterKey) -> CreateDataKey {
         CreateDataKey {
             client_enc: self,