tools/lib/reference_doc/macro/src/lib.rs

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

use proc_macro::TokenStream;

mod derive_reference_doc;

/// Macro that adds an implementation of the trait MarkdownReferenceDocGenerator
/// to structs with `derive(ReferenceDoc)`. The trait adds the fn
/// `get_markdown_reference_docs()`. The return value is generated by consuming the
/// struct's field names, types, and doc comments. Markdown headers in the
/// doc comments are appropriately indendented based on the context in which
/// they appear.
///
/// Attributes: none
///
/// Example:
///
/// ```rust
/// #[derive(ReferenceDoc)]
/// struct MyStruct {
///      /// This comment will appear for `field`, and can contain markdown.
///      /// It will be prefixed by a generated heading.
///      ///
///      /// Other comments may link to the generated heading using the hash `#field`.
///      /// For example, [this](#field) is a self-referencing link.
///      field: i32,
/// }
/// ```
#[proc_macro_derive(ReferenceDoc, attributes(reference_doc))]
pub fn derive_reference_doc(input: TokenStream) -> TokenStream {
    let ast = syn::parse(input).expect("could not parse input");
    derive_reference_doc::impl_derive_reference_doc(ast)
        .unwrap_or_else(|err| err.to_compile_error())
        .into()
}