document struct generation macro

rpc/monero-rpc-types/src/binary.rs

@@ -1,4 +1,4 @@
-//! TODO
+//! Binary types.
 
 //---------------------------------------------------------------------------------------------------- Import
 

rpc/monero-rpc-types/src/data.rs

@@ -1,4 +1,4 @@
-//! TODO
+//! Misc data structures within other types.
 
 //---------------------------------------------------------------------------------------------------- Import
 

rpc/monero-rpc-types/src/json.rs

@@ -1,18 +1,38 @@
-//! TODO
+//! JSON types.
 //!
 //! <https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454/src/rpc/daemon_messages.h>.
 
 //---------------------------------------------------------------------------------------------------- Import
-use crate::macros::define_monero_rpc_type_struct;
+use crate::{macros::define_monero_rpc_type_struct, misc::Status};
 
-//---------------------------------------------------------------------------------------------------- TODO
+//---------------------------------------------------------------------------------------------------- Struct definitions
 define_monero_rpc_type_struct! {
-    get_height,
-    daemon_messages.h => 81..=87,
-    GetHeight { height: 123 } => r#"{"height":123}"#,
-    GetHeight {
-        /// A block height.
-        height: u64,
+    // The markdown tag for Monero RPC documentation. Not necessarily the endpoint.
+    get_block_count,
+    // The `$file.$extension` in which this type is defined in the Monero
+    // codebase in the `rpc/` directory, followed by the specific lines.
+    core_rpc_server_commands_defs.h => 919..=933,
+    // The type and its compacted JSON string form, used in example doc-test.
+    GetBlockCount { count: 123, status: Status::Ok, untrusted: false } =>
+    r#"{"count":123,"status":"OK","untrusted":false}"#,
+    // The actual type definitions.
+    // If there are any additional attributes (`/// docs` or `#[derive]`s)
+    // for the struct, they go here, e.g.:
+    // #[derive(MyCustomDerive)]
+    GetBlockCount /* <- The type name */ {
+        // Within the `{}` is an infinite matching pattern of:
+        // ```
+        // $ATTRIBUTES
+        // $FIELD_NAME: $FIELD_TYPE,
+        // ```
+        // The struct generated and all fields are `pub`.
+
+        /// How many blocks are in the longest chain known to the node.
+        count: u64,
+        /// General RPC error code. "OK" means everything looks good.
+        status: Status,
+        /// Whether the node is untrusted (see Monero docs).
+        untrusted: bool,
     }
 }
 

rpc/monero-rpc-types/src/lib.rs

@@ -102,4 +102,5 @@ pub mod binary;
 pub mod data;
 pub mod json;
 pub mod macros;
-pub mod mix;
+pub mod misc;
+pub mod other;

rpc/monero-rpc-types/src/macros.rs

@@ -3,27 +3,41 @@
 //! These generate repetitive documentation, tests, etc.
 
 //---------------------------------------------------------------------------------------------------- Struct definition
-/// TODO
+/// A template for generating a `struct` with a bunch of information filled out.
+///
+/// It's best to see the output of this macro via the documentation
+/// of the generated structs via `cargo doc`s to see which parts
+/// generate which docs.
+///
+/// See [`crate::json::GetHeight`] for example usage.
 macro_rules! define_monero_rpc_type_struct {
     (
-        $monero_daemon_rpc_doc_link:ident, // TODO
-        $monero_code_filename:ident.$monero_code_filename_extension:ident => // TODO
-        $monero_code_line_start:literal..= // TODO
-        $monero_code_line_end:literal, // TODO
-        $type_literal:expr => // TODO
-        $type_as_json:literal, // TODO
-        $type_name:ident { // TODO
+        // The markdown tag for Monero RPC documentation. Not necessarily the endpoint.
+        $monero_daemon_rpc_doc_link:ident,
+
+        // The `$file.$extension` in which this type is defined in the Monero
+        // codebase in the `rpc/` directory, followed by the specific lines.
+        $monero_code_filename:ident.$monero_code_filename_extension:ident =>
+        $monero_code_line_start:literal..=$monero_code_line_end:literal,
+
+        // A real literal type expression, and its JSON string form.
+        // Used in example doc-test.
+        $type_literal:expr => $type_as_json:literal,
+
+        // The actual `struct` name and any doc comments, derives, etc.
+        $( #[$type_attr:meta] )*
+        $type_name:ident {
+            // And any fields.
             $(
-                $( #[$field_attr:meta] )* // TODO
-                $field:ident: $type:ty, // TODO
+                $( #[$field_attr:meta] )*
+                $field:ident: $field_type:ty,
             )*
         }
     ) => {
-        ///
+        $( #[$type_attr:meta] )*
         #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
         #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
         ///
-        // Documents the original Monero type and where it is located in `monero-project/monero`.
         #[doc = concat!(
             "",
             "Definition: [`",
@@ -51,10 +65,9 @@ macro_rules! define_monero_rpc_type_struct {
             ").",
         )]
         ///
-        // Doc-test that tests (de)serialization.
         /// # `serde` example
         /// ```rust
-        #[doc = "# use monero_rpc_types::{json::*, binary::*, data::*, mix::*};"]
+        #[doc = "# use monero_rpc_types::{json::*, binary::*, data::*, misc::*, other::*};"]
         #[doc = concat!("let t = ", stringify!($type_literal), ";")]
         #[doc = "let string = serde_json::to_string(&t).unwrap();"]
         #[doc = concat!("assert_eq!(string, ", stringify!($type_as_json), ");")]
@@ -62,11 +75,10 @@ macro_rules! define_monero_rpc_type_struct {
         #[doc = "let t2 = serde_json::from_str(&string).unwrap();"]
         #[doc = "assert_eq!(t, t2);"]
         /// ```
-        // The type.
         pub struct $type_name {
             $(
                 $( #[$field_attr] )*
-                pub $field: $type,
+                pub $field: $field_type,
             )*
         }
     };

rpc/monero-rpc-types/src/mix.rs

@@ -1,11 +0,0 @@
-//! TODO
-
-//---------------------------------------------------------------------------------------------------- Import
-
-//---------------------------------------------------------------------------------------------------- TODO
-
-//---------------------------------------------------------------------------------------------------- Tests
-#[cfg(test)]
-mod test {
-    // use super::*;
-}

rpc/monero-rpc-types/src/other.rs

@@ -0,0 +1,38 @@
+//! Other endpoint types.
+//!
+//! <https://github.com/monero-project/monero/blob/cc73fe71162d564ffda8e549b79a350bca53c454/src/rpc/daemon_messages.h>.
+
+//---------------------------------------------------------------------------------------------------- Import
+use crate::macros::define_monero_rpc_type_struct;
+
+//---------------------------------------------------------------------------------------------------- TODO
+define_monero_rpc_type_struct! {
+    // The markdown tag for Monero RPC documentation. Not necessarily the endpoint.
+    get_height,
+    // The `$file.$extension` in which this type is defined in the Monero
+    // codebase in the `rpc/` directory, followed by the specific lines.
+    daemon_messages.h => 81..=87,
+    // The type and its compacted JSON string form, used in example doc-test.
+    GetHeight { height: 123 } => r#"{"height":123}"#,
+    // The actual type definitions.
+    // If there are any additional attributes (`/// docs` or `#[derive]`s)
+    // for the struct, they go here, e.g.:
+    // #[derive(MyCustomDerive)]
+    GetHeight /* <- The type name */ {
+        // Within the `{}` is an infinite matching pattern of:
+        // ```
+        // $ATTRIBUTES
+        // $FIELD_NAME: $FIELD_TYPE,
+        // ```
+        // The struct generated and all fields are `pub`.
+
+        /// A block height.
+        height: u64,
+    }
+}
+
+//---------------------------------------------------------------------------------------------------- Tests
+#[cfg(test)]
+mod test {
+    // use super::*;
+}