From 50f55d94e2db2905a4962216e662cef0ec7c2c83 Mon Sep 17 00:00:00 2001
From: Hirrolot <hirrolot@gmail.com>
Date: Wed, 28 Aug 2024 18:39:09 -0400
Subject: [PATCH] Simplify a top-level comment (the `composite_state` example)

---
 crates/teloxide/examples/composite_state.rs | 74 +++++++++++----------
 1 file changed, 38 insertions(+), 36 deletions(-)

diff --git a/crates/teloxide/examples/composite_state.rs b/crates/teloxide/examples/composite_state.rs
index 347f7b84..661e1c49 100644
--- a/crates/teloxide/examples/composite_state.rs
+++ b/crates/teloxide/examples/composite_state.rs
@@ -1,39 +1,41 @@
-/*
-    This example demonstrates how to split the dialogue state into substates represented by separated enums.
-
-    Imagine that your dialogue state is really complex and logically it can be represented as
-    separate stages, say `user setup` and `do stuff`.
-
-    Instead of inflate the single state enum:
-    ```
-    #[derive(Clone, Default)]
-    pub enum State {
-        #[default]
-        Unconfigured,
-        ReceiveFullName,
-        ReceiveAge { full_name: String },
-        ...many more state variants...
-        Idle
-    }
-    ```
-    You rather should do the following:
-    ```
-    #[derive(Clone, Default)]
-    pub enum GlobalState {
-        #[default]
-        Unconfigured,
-        UserSetup(UserSetup),
-        ...many more stages, each of which is represented by a separate enum...
-        Idle
-    }
-
-    #[derive(Clone)]
-    enum UserSetup {
-        ReceiveFullName,
-        ReceiveAge { full_name: String },
-    }
-    ```
-*/
+//! Imagine that your dialogue state is logically represented by separate
+//! stages, say "setup stage", "perform action stage", etc. Instead of inflating
+//! a single-state enumeration like this:
+//! ```
+//! #[derive(Clone, Default)]
+//! pub enum State {
+//!     #[default]
+//!     Unconfigured,
+//!     ReceiveFullName,
+//!     ReceiveAge {
+//!         full_name: String,
+//!     },
+//!     // Many more variants...
+//!     Idle,
+//! }
+//! ```
+//!
+//! The more appropriate way is to nest enumerations like this:
+//! ```
+//! #[derive(Clone, Default)]
+//! pub enum GlobalState {
+//!     #[default]
+//!     Unconfigured,
+//!     UserSetup(UserSetup),
+//!     // Many more complex stages...
+//!     Idle,
+//! }
+//!
+//! #[derive(Clone)]
+//! enum UserSetup {
+//!     ReceiveFullName,
+//!     ReceiveAge { full_name: String },
+//! }
+//!
+//! // More enumeration definitions...
+//! ```
+//!
+//! This example demonstrates how to achieve this `teloxide` design pattern.
 
 use teloxide::{
     dispatching::{dialogue::InMemStorage, MessageFilterExt},