doc processing

CHANGELOG.md

@@ -23,6 +23,7 @@ adheres to [Semantic Versioning][semver].
   generated inside the said module.
 * Supplying ones own enums for state, input and output in the proc-macro (#10).
 * An optional possibility to generate Mermaid diagrams.
+* Processing doc comments to generate the state machine module documentation.
 
 ## [0.6.2] - 2024-05-11
 ### Changed

Cargo.toml

@@ -1,3 +1,3 @@
 [workspace]
 resolver = "2"
-members = ["rust-fsm", "rust-fsm-dsl"]
+members = ["rust-fsm", "rust-fsm-dsl", "doc-example"]

README.md

@@ -70,6 +70,7 @@ use rust_fsm::*;
 state_machine! {
     #[derive(Debug)]
     #[repr(C)]
+    /// A Circuit Breaker state machine.
     circuit_breaker(Closed)
 
     Closed(Unsuccessful) => Open [SetupTimer],
@@ -198,6 +199,12 @@ controlled by the `diagram` feature, which is non-default. The diagrams are
 generated in the [Mermaid][mermaid] format. This feature includes the Mermaid
 script into the documentation page.
 
+To see this in action, download the repository and run:
+
+```bash
+cargo doc -p doc-example --open
+```
+
 ### Without DSL
 
 The `state_machine` macro has limited capabilities (for example, a state

doc-example/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "doc-example"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+rust-fsm = { path = "../rust-fsm", version = "0.6.2", features = ["diagram"] }

doc-example/src/lib.rs

@@ -0,0 +1,15 @@
+use rust_fsm::state_machine;
+
+state_machine! {
+    /// A dummy implementation of the Circuit Breaker pattern to demonstrate
+    /// capabilities of its library DSL for defining finite state machines.
+    /// https://martinfowler.com/bliki/CircuitBreaker.html
+    pub circuit_breaker(Closed)
+
+    Closed(Unsuccessful) => Open [SetupTimer],
+    Open(TimerTriggered) => HalfOpen,
+    HalfOpen => {
+        Successful => Closed,
+        Unsuccessful => Open [SetupTimer]
+    }
+}

rust-fsm-dsl/src/lib.rs

@@ -7,7 +7,7 @@ extern crate proc_macro;
 use proc_macro::TokenStream;
 use quote::{quote, ToTokens};
 use std::{collections::BTreeSet, iter::FromIterator};
-use syn::{parse_macro_input, Ident};
+use syn::{parse_macro_input, Attribute, Ident};
 
 mod parser;
 
@@ -20,17 +20,19 @@ struct Transition<'a> {
     output: &'a Option<Ident>,
 }
 
+fn attrs_to_token_stream(attrs: Vec<Attribute>) -> proc_macro2::TokenStream {
+    let attrs = attrs.into_iter().map(ToTokens::into_token_stream);
+    proc_macro2::TokenStream::from_iter(attrs)
+}
+
 #[proc_macro]
 /// Produce a state machine definition from the provided `rust-fmt` DSL
 /// description.
 pub fn state_machine(tokens: TokenStream) -> TokenStream {
     let input = parse_macro_input!(tokens as parser::StateMachineDef);
 
-    let attrs = input
-        .attributes
-        .into_iter()
-        .map(ToTokens::into_token_stream);
-    let attrs = proc_macro2::TokenStream::from_iter(attrs);
+    let doc = attrs_to_token_stream(input.doc);
+    let attrs = attrs_to_token_stream(input.attributes);
 
     if input.transitions.is_empty() {
         let output = quote! {
@@ -171,6 +173,7 @@ pub fn state_machine(tokens: TokenStream) -> TokenStream {
     let diagram = quote!();
 
     let output = quote! {
+        #doc
         #diagram
         #visibility mod #fsm_name {
             #attrs

rust-fsm-dsl/src/parser.rs

@@ -116,6 +116,7 @@ impl Parse for TransitionDef {
 /// }
 /// ```
 pub struct StateMachineDef {
+    pub doc: Vec<Attribute>,
     /// The visibility modifier (applies to all generated items)
     pub visibility: Visibility,
     pub name: Ident,
@@ -130,12 +131,16 @@ pub struct StateMachineDef {
 impl Parse for StateMachineDef {
     fn parse(input: ParseStream) -> Result<Self> {
         let mut state_machine_attributes = Vec::new();
+        let mut doc = Vec::new();
         let attributes = Attribute::parse_outer(input)?
             .into_iter()
             .filter_map(|attribute| {
                 if attribute.path().is_ident("state_machine") {
                     state_machine_attributes.push(attribute);
                     None
+                } else if attribute.path().is_ident("doc") {
+                    doc.push(attribute);
+                    None
                 } else {
                     Some(attribute)
                 }
@@ -177,6 +182,7 @@ impl Parse for StateMachineDef {
             .collect();
 
         Ok(Self {
+            doc,
             visibility,
             name,
             initial_state,