Skip to content

fix: do not loose docs in stored_proc macro

Егор Ивков requested to merge capture-docs-in-proc into master

Problem

Previously if any doc comment was given to a stored proc, it was lost when generating docs with cargo doc.

/// This comment will be lost
#[proc]
fn some_proc() -> usize {
    0
}

Solution

Before running a macro expansion Rust transforms doc comments into #[doc = "some comment"] attributes, 1 attribute per 1 line of comment.

Therefore all that was needed was to capture attributes and add them with #(#attrs)* to quote! expansion.

Example Token Tree

For code

/// Some comment
#[proc]
fn some_proc() -> usize {
    0
}

TokenStream parsed as Item enum (from syn):

Fn(
               ItemFn {
                   attrs: [
                       Attribute {
                           pound_token: Pound,
                           style: Outer,
                           bracket_token: Bracket,
                           path: Path {
                               leading_colon: None,
                               segments: [
                                   PathSegment {
                                       ident: Ident {
                                           ident: "doc",
                                           span: #0 bytes(230..246),
                                       },
                                       arguments: None,
                                   },
                               ],
                           },
                           tokens: TokenStream [
                               Punct {
                                   ch: '=',
                                   spacing: Alone,
                                   span: #0 bytes(230..246),
                               },
                               Literal {
                                   kind: Str,
                                   symbol: " Some comment",
                                   suffix: None,
                                   span: #0 bytes(230..246),
                               },
                           ],
                       },
                   ],
                   vis: Inherited,
                   sig: Signature {
                       constness: None,
                       asyncness: None,
                       unsafety: None,
                       abi: None,
                       fn_token: Fn,
                       ident: Ident {
                           ident: "some_proc",
                           span: #0 bytes(258..267),
                       },
                       generics: Generics {
                           lt_token: None,
                           params: [],
                           gt_token: None,
                           where_clause: None,
                       },
                       paren_token: Paren,
                       inputs: [],
                       variadic: None,
                       output: Type(
                           RArrow,
                           Path(
                               TypePath {
                                   qself: None,
                                   path: Path {
                                       leading_colon: None,
                                       segments: [
                                           PathSegment {
                                               ident: Ident {
                                                   ident: "usize",
                                                   span: #0 bytes(273..278),
                                               },
                                               arguments: None,
                                           },
                                       ],
                                   },
                               },
                           ),
                       ),
                   },
                   block: Block {
                       brace_token: Brace,
                       stmts: [
                           Expr(
                               Lit(
                                   ExprLit {
                                       attrs: [],
                                       lit: Int(
                                           LitInt {
                                               token: 0,
                                           },
                                       ),
                                   },
                               ),
                           ),
                       ],
                   },
               },
)

Merge request reports