feat: add an option to include rustdoc in ABI

examples/abi/Cargo.toml

@@ -8,7 +8,8 @@ edition = "2021"
 crate-type = ["cdylib"]
 
 [dependencies]
-near-sdk = { path = "../../near-sdk", features = ["abi"] }
+# "abi-doc" is an optional feature that includes contract functions' rustdocs into the ABI file
+near-sdk = { path = "../../near-sdk", features = ["abi", "abi-doc"] }
 serde = { version = "1", features = ["derive"] }
 schemars = "0.8"
 

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/Cargo.toml

@@ -22,3 +22,4 @@ Inflector = { version = "0.11.4", default-features = false, features = [] }
 
 [features]
 abi = []
+abi-doc = ["abi"]

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

@@ -41,6 +41,14 @@ 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();
+        #[cfg(feature = "abi-doc")]
+        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 },
+            };
+        #[cfg(not(feature = "abi-doc"))]
+        let function_doc = 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 +161,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,4 @@
 pub mod abi_generator;
 pub mod abi_visitor;
+#[cfg(feature = "abi-doc")]
+mod doc;

near-sdk/Cargo.toml

@@ -52,6 +52,7 @@ default = ["wee_alloc", "unit-testing"]
 expensive-debug = []
 unstable = ["once_cell"]
 abi = ["schemars", "near-sdk-macros/abi"]
+abi-doc = ["abi", "near-sdk-macros/abi-doc"]
 unit-testing = ["near-vm-logic", "near-primitives-core", "near-primitives", "near-crypto"]
 
 [package.metadata.docs.rs]

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,