使用syn插入文档注释为何生成#[doc=...]而非///格式？

我用syn库编写代码，给Rust源码里的结构体、枚举和函数添加文档注释，代码如下：

let mut file: File = syn::parse_str(file_content.as_str()).expect("Failed to parse Rust code");

for item in &mut file.items {
    // Use quote! to generate a comment and append it to the item
    let mut comment: Attribute = parse_quote! {
        /// This is a generated comment.
    };

    comment.style = AttrStyle::Outer;

    match item {
        Item::Struct(ref mut s) => {
            s.attrs.push(comment.clone());
        }
        Item::Enum(ref mut e) => {
            e.attrs.push(comment.clone());
        }
        Item::Fn(ref mut f) => {
            f.attrs.push(comment.clone());
        }
        _ => {}
    }
}

执行后得到的结果是：

#[doc = r" This is a generated comment."]
pub struct MTContainerGuardMut<'a, T> {
    data: *mut T,
    #[cfg(debug_assertions)]
    flag: &'a AtomicBool,
    #[cfg(not(debug_assertions))]
    _phantom: PhantomData<&'a ()>,
}

我预期生成/// This is a generated comment.格式的注释，请问哪里出错了？

核心原因 #

/// 是Rust提供的文档注释语法糖，它和 #[doc = r" This is a generated comment."] 在语义上完全等价，syn库内部会将这两种形式统一解析为相同的Attribute结构体。当你将修改后的AST转换为代码时，syn默认的Token生成逻辑会选择输出#[doc]的原始属性形式，而非语法糖格式。

另外，你的代码里手动设置comment.style = AttrStyle::Outer是多余的——parse_quote! { /// ... }生成的Attribute已经是Outer样式，不需要额外修改。

解决方案 #

如果你希望最终输出///格式的注释，有两种可行方式：

• 用rustfmt格式化输出结果
  Rust的官方格式化工具rustfmt会自动将#[doc = "..."]转换为///语法糖格式。你只需将生成的代码传入rustfmt处理即可，比如在代码中调用rustfmt的API，或者将输出内容保存为文件后用rustfmt命令行工具格式化。

• 直接生成///格式的Token流
  如果你不想依赖rustfmt，可以绕过syn的Attribute结构，直接在生成代码时插入///行。不过这种方式需要你直接操作TokenStream，而非修改AST的attrs字段，示例如下：

  use quote::quote;
  
  // 假设item是你处理后的AST节点
  let output = quote! {
      /// This is a generated comment.
      #item
  };
  

  这种方式会直接在目标项前插入///注释，输出时自然就是你想要的格式。

内容的提问来源于stack exchange，提问作者Makogan