Simplify a top-level comment (the composite_state example)

crates/teloxide/examples/composite_state.rs

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