feat: add an option to include rustdoc in ABI (#876)

examples/abi/res/abi.json

@@ -11,6 +11,7 @@
     "functions": [
       {
         "name": "add",
+        "doc": " Adds two pairs point-wise.",
         "is_view": true,
         "params": [
           {

examples/abi/src/lib.rs

@@ -18,6 +18,7 @@ pub struct Adder {}
 
 #[near_bindgen]
 impl Adder {
+    /// Adds two pairs point-wise.
     pub fn add(&self, a: Pair, b: Pair) -> Pair {
         sum_pair(&a, &b)
     }

near-sdk-macros/src/core_impl/abi/abi_generator.rs

@@ -41,6 +41,11 @@ impl ImplItemMethodInfo {
     /// If args are serialized with Borsh it will not include `#[derive(borsh::BorshSchema)]`.
     pub fn abi_struct(&self) -> TokenStream2 {
         let function_name_str = self.attr_signature_info.ident.to_string();
+        let function_doc =
+            match super::doc::parse_rustdoc(&self.attr_signature_info.non_bindgen_attrs) {
+                Some(doc) => quote! { Some(#doc.to_string()) },
+                None => quote! { None },
+            };
         let is_view = matches!(&self.attr_signature_info.method_type, &MethodType::View);
         let is_init = matches!(
             &self.attr_signature_info.method_type,
@@ -153,6 +158,7 @@ impl ImplItemMethodInfo {
         quote! {
              near_sdk::__private::AbiFunction {
                  name: #function_name_str.to_string(),
+                 doc: #function_doc,
                  is_view: #is_view,
                  is_init: #is_init,
                  is_payable: #is_payable,

near-sdk-macros/src/core_impl/abi/doc.rs

@@ -0,0 +1,25 @@
+use syn::{Attribute, Lit::Str, Meta::NameValue, MetaNameValue};
+
+pub fn parse_rustdoc(attrs: &[Attribute]) -> Option<String> {
+    let doc = attrs
+        .iter()
+        .filter_map(|attr| {
+            if attr.path.is_ident("doc") {
+                if let NameValue(MetaNameValue { lit: Str(s), .. }) = attr.parse_meta().ok()? {
+                    Some(s.value())
+                } else {
+                    None
+                }
+            } else {
+                None
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("\n");
+
+    if doc.is_empty() {
+        None
+    } else {
+        Some(doc)
+    }
+}

near-sdk-macros/src/core_impl/abi/mod.rs

@@ -1,2 +1,3 @@
 pub mod abi_generator;
 pub mod abi_visitor;
+mod doc;

near-sdk/src/private/abi.rs

@@ -111,6 +111,9 @@ impl Abi {
 #[derive(Clone, Serialize, Deserialize, Debug, PartialEq)]
 pub struct AbiFunction {
     pub name: String,
+    /// Human-readable documentation parsed from the source file.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub doc: Option<String>,
     /// Whether function does not modify the state.
     #[serde(default, skip_serializing_if = "is_false")]
     pub is_view: bool,