RUST-2103 Better documentation for action options, batch 2 (#1261)

Author: abr-egn

macros/src/lib.rs

@@ -1,15 +1,18 @@
 extern crate proc_macro;
 
-use macro_magic::import_tokens_attr;
+use macro_magic::{import_tokens_attr, mm_core::ForeignPath};
 use quote::{quote, ToTokens};
 use syn::{
     braced,
+    bracketed,
     parenthesized,
     parse::{Parse, ParseStream},
     parse_macro_input,
     parse_quote,
     parse_quote_spanned,
+    punctuated::Punctuated,
     spanned::Spanned,
+    token::Bracket,
     Attribute,
     Block,
     Error,
@@ -206,15 +209,15 @@ impl Parse for ActionImplAttrs {
 }
 
 /// Parse an identifier with a specific expected value.
-fn parse_name(input: ParseStream, name: &str) -> syn::Result<()> {
+fn parse_name(input: ParseStream, name: &str) -> syn::Result<Ident> {
     let ident = input.parse::<Ident>()?;
     if ident.to_string() != name {
         return Err(Error::new(
             ident.span(),
             format!("expected '{}', got '{}'", name, ident),
         ));
     }
-    Ok(())
+    Ok(ident)
 }
 
 macro_rules! compile_error {
@@ -461,13 +464,15 @@ impl Parse for OptionSetter {
 }
 
 #[import_tokens_attr]
+#[with_custom_parsing(OptionSettersArgs)]
 #[proc_macro_attribute]
 pub fn option_setters_2(
     attr: proc_macro::TokenStream,
     item: proc_macro::TokenStream,
 ) -> proc_macro::TokenStream {
     let opt_struct = parse_macro_input!(attr as ItemStruct);
     let mut impl_in = parse_macro_input!(item as ItemImpl);
+    let args = parse_macro_input!(__custom_tokens as OptionSettersArgs);
 
     // Gather information about each option struct field
     struct OptInfo {
@@ -545,21 +550,134 @@ pub fn option_setters_2(
                 self.options().#name = Some(#value);
                 self
             }
+        });
+    }
+
+    // Build rustdoc information.
+    let doc_name = args.doc_name;
+    let mut doc_impl = impl_in.clone();
+    // Synthesize a fn entry for each extra listed so it'll get a rustdoc entry
+    if let Some((_, extra)) = args.extra {
+        for name in &extra.names {
+            doc_impl.items.push(parse_quote! {
+                pub fn #name(&self) {}
+            });
+        }
+    }
+
+    // All done.  Export the tokens for doc use as their own distinct (uncompiled) item.
+    quote! {
+        #impl_in
+
+        #[macro_magic::export_tokens_no_emit(#doc_name)]
+        #doc_impl
+    }
+    .into()
+}
+
+struct OptionSettersArgs {
+    source_text: (Ident, Token![=]), // source =
+    foreign_path: syn::Path,
+    name_text: (Token![,], Ident, Token![=]), // , doc_name =
+    doc_name: Ident,
+    extra: Option<(Token![,], OptionSettersArgsExtra)>,
+}
+
+#[derive(Debug)]
+struct OptionSettersArgsExtra {
+    extra_text: (Ident, Token![=]), // extra =
+    bracket: Bracket,
+    names: Punctuated<Ident, Token![,]>,
+}
+
+impl Parse for OptionSettersArgs {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let source_text = (parse_name(input, "source")?, input.parse()?);
+        let foreign_path = input.parse()?;
+        let name_text = (
+            input.parse()?,
+            parse_name(input, "doc_name")?,
+            input.parse()?,
+        );
+        let doc_name = input.parse()?;
+        let extra = if input.is_empty() {
+            None
+        } else {
+            Some((input.parse()?, input.parse()?))
+        };
+        Ok(Self {
+            source_text,
+            foreign_path,
+            name_text,
+            doc_name,
+            extra,
         })
     }
+}
+
+impl ToTokens for OptionSettersArgs {
+    fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
+        let Self {
+            source_text,
+            foreign_path,
+            name_text,
+            doc_name,
+            extra,
+        } = &self;
+        tokens.extend(source_text.0.to_token_stream());
+        tokens.extend(source_text.1.to_token_stream());
+        tokens.extend(foreign_path.to_token_stream());
+        tokens.extend(name_text.0.to_token_stream());
+        tokens.extend(name_text.1.to_token_stream());
+        tokens.extend(name_text.2.to_token_stream());
+        tokens.extend(doc_name.to_token_stream());
+        if let Some(extra) = extra {
+            tokens.extend(extra.0.to_token_stream());
+            tokens.extend(extra.1.to_token_stream());
+        }
+    }
+}
 
-    // All done.
-    impl_in.to_token_stream().into()
+impl ForeignPath for OptionSettersArgs {
+    fn foreign_path(&self) -> &syn::Path {
+        &self.foreign_path
+    }
+}
+
+impl Parse for OptionSettersArgsExtra {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let extra_text = (parse_name(input, "extra")?, input.parse::<Token![=]>()?);
+        let content;
+        let bracket = bracketed!(content in input);
+        let names = Punctuated::parse_separated_nonempty(&content)?;
+        Ok(Self {
+            extra_text,
+            bracket,
+            names,
+        })
+    }
+}
+
+impl ToTokens for OptionSettersArgsExtra {
+    fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
+        tokens.extend(self.extra_text.0.to_token_stream());
+        tokens.extend(self.extra_text.1.to_token_stream());
+        self.bracket.surround(tokens, |content| {
+            content.extend(self.names.to_token_stream());
+        });
+    }
 }
 
 #[import_tokens_attr]
+#[with_custom_parsing(OptionsDocArgs)]
 #[proc_macro_attribute]
 pub fn options_doc(
     attr: proc_macro::TokenStream,
     item: proc_macro::TokenStream,
 ) -> proc_macro::TokenStream {
     let setters = parse_macro_input!(attr as ItemImpl);
     let mut impl_fn = parse_macro_input!(item as ImplItemFn);
+    let args = parse_macro_input!(__custom_tokens as OptionsDocArgs);
 
     // Collect a list of names from the setters impl
     let mut setter_names = vec![];
@@ -586,8 +704,12 @@ pub fn options_doc(
     impl_fn.attrs.push(parse_quote! {
         #[doc = ""]
     });
+    let preamble = format!(
+        "These methods can be chained before `{}` to set options:",
+        if args.is_async() { ".await" } else { "run" }
+    );
     impl_fn.attrs.push(parse_quote! {
-        #[doc = "These methods can be chained before calling `.await` to set options:"]
+        #[doc = #preamble]
     });
     for name in setter_names {
         let docstr = format!("  * [`{0}`]({1}::{0})", name, doc_path);
@@ -597,3 +719,43 @@ pub fn options_doc(
     }
     impl_fn.into_token_stream().into()
 }
+
+struct OptionsDocArgs {
+    foreign_path: syn::Path,
+    sync: Option<(Token![,], Ident)>,
+}
+
+impl OptionsDocArgs {
+    fn is_async(&self) -> bool {
+        self.sync.is_none()
+    }
+}
+
+impl Parse for OptionsDocArgs {
+    fn parse(input: ParseStream) -> syn::Result<Self> {
+        let foreign_path = input.parse()?;
+        let sync = if input.is_empty() {
+            None
+        } else {
+            Some((input.parse()?, parse_name(input, "sync")?))
+        };
+
+        Ok(Self { foreign_path, sync })
+    }
+}
+
+impl ToTokens for OptionsDocArgs {
+    fn to_tokens(&self, tokens: &mut proc_macro2::TokenStream) {
+        tokens.extend(self.foreign_path.to_token_stream());
+        if let Some((comma, ident)) = &self.sync {
+            tokens.extend(comma.to_token_stream());
+            tokens.extend(ident.to_token_stream());
+        }
+    }
+}
+
+impl ForeignPath for OptionsDocArgs {
+    fn foreign_path(&self) -> &syn::Path {
+        &self.foreign_path
+    }
+}

src/action/aggregate.rs

@@ -1,9 +1,11 @@
 use std::{marker::PhantomData, time::Duration};
 
-use bson::Document;
+use bson::{Bson, Document};
+use mongodb_internal_macros::{option_setters_2, options_doc};
 
 use crate::{
-    coll::options::AggregateOptions,
+    coll::options::{AggregateOptions, Hint},
+    collation::Collation,
     error::Result,
     operation::aggregate::AggregateTarget,
     options::{ReadConcern, WriteConcern},
@@ -16,7 +18,7 @@ use crate::{
     SessionCursor,
 };
 
-use super::{action_impl, deeplink, option_setters, CollRef, ExplicitSession, ImplicitSession};
+use super::{action_impl, deeplink, CollRef, ExplicitSession, ImplicitSession};
 
 impl Database {
     /// Runs an aggregation operation.
@@ -28,6 +30,7 @@ impl Database {
     /// returned cursor will be a [`SessionCursor`]. If [`with_type`](Aggregate::with_type) was
     /// called, the returned cursor will be generic over the `T` specified.
     #[deeplink]
+    #[options_doc(aggregate_setters)]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         Aggregate {
             target: AggregateTargetRef::Database(self),
@@ -52,6 +55,7 @@ where
     /// returned cursor will be a [`SessionCursor`]. If [`with_type`](Aggregate::with_type) was
     /// called, the returned cursor will be generic over the `T` specified.
     #[deeplink]
+    #[options_doc(aggregate_setters)]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         Aggregate {
             target: AggregateTargetRef::Collection(CollRef::new(self)),
@@ -75,6 +79,7 @@ impl crate::sync::Database {
     /// [`crate::sync::SessionCursor`]. If [`with_type`](Aggregate::with_type) was called, the
     /// returned cursor will be generic over the `T` specified.
     #[deeplink]
+    #[options_doc(aggregate_setters, sync)]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         self.async_database.aggregate(pipeline)
     }
@@ -95,6 +100,7 @@ where
     /// `crate::sync::SessionCursor`. If [`with_type`](Aggregate::with_type) was called, the
     /// returned cursor will be generic over the `T` specified.
     #[deeplink]
+    #[options_doc(aggregate_setters, sync)]
     pub fn aggregate(&self, pipeline: impl IntoIterator<Item = Document>) -> Aggregate {
         self.async_collection.aggregate(pipeline)
     }
@@ -111,39 +117,11 @@ pub struct Aggregate<'a, Session = ImplicitSession, T = Document> {
     _phantom: PhantomData<T>,
 }
 
-impl<Session, T> Aggregate<'_, Session, T> {
-    option_setters!(options: AggregateOptions;
-        allow_disk_use: bool,
-        batch_size: u32,
-        bypass_document_validation: bool,
-        collation: crate::collation::Collation,
-        comment: bson::Bson,
-        hint: crate::coll::options::Hint,
-        max_await_time: Duration,
-        max_time: Duration,
-        read_concern: ReadConcern,
-        selection_criteria: SelectionCriteria,
-        write_concern: WriteConcern,
-        let_vars: Document,
-    );
-}
-
-impl<'a, T> Aggregate<'a, ImplicitSession, T> {
-    /// Use the provided session when running the operation.
-    pub fn session(
-        self,
-        value: impl Into<&'a mut ClientSession>,
-    ) -> Aggregate<'a, ExplicitSession<'a>> {
-        Aggregate {
-            target: self.target,
-            pipeline: self.pipeline,
-            options: self.options,
-            session: ExplicitSession(value.into()),
-            _phantom: PhantomData,
-        }
-    }
-}
-
+#[option_setters_2(
+    source = crate::coll::options::AggregateOptions,
+    doc_name = aggregate_setters,
+    extra = [session]
+)]
 impl<'a, Session, T> Aggregate<'a, Session, T> {
     /// Use the provided type for the returned cursor.
     ///
@@ -178,6 +156,22 @@ impl<'a, Session, T> Aggregate<'a, Session, T> {
     }
 }
 
+impl<'a, T> Aggregate<'a, ImplicitSession, T> {
+    /// Use the provided session when running the operation.
+    pub fn session(
+        self,
+        value: impl Into<&'a mut ClientSession>,
+    ) -> Aggregate<'a, ExplicitSession<'a>> {
+        Aggregate {
+            target: self.target,
+            pipeline: self.pipeline,
+            options: self.options,
+            session: ExplicitSession(value.into()),
+            _phantom: PhantomData,
+        }
+    }
+}
+
 #[action_impl(sync = crate::sync::Cursor<T>)]
 impl<'a, T> Action for Aggregate<'a, ImplicitSession, T> {
     type Future = AggregateFuture;