Command: add documentation

Author: fadeevab

behavioral/command/README.md

@@ -1,11 +1,34 @@
 # Command
 
-Command is behavioral design pattern that converts requests or simple operations into objects.
+**Command** is behavioral design pattern that converts requests or
+simple operations into objects.
+
+A specific thing about Command Pattern implementation in 🦀 Rust is that
+a command instance should NOT hold a permanent reference to global context,
+instead the latter should be passed from top to down as a mutable parameter
+of the "`execute`" method:
+
+```rust
+fn execute(&mut self, app: &mut cursive::Cursive) -> bool;
+```
 
 ## Text Editor: Commands and Undo
 
+How to launch:
+
 ```bash
-cargo run
+cargo run --bin command
 ```
 
+Key points:
+
+- Each button runs a separate command.
+- Because a command is represented as an object, it can be pushed into a
+  `history` array in order to be undone later.
+- TUI is created with `cursive` crate.
+
 ![Text Editor screenshot](res/editor.png)
+
+## Notes
+
+This example is inspired by [Command in Java (Example)](https://refactoring.guru/design-patterns/command/java/example).

behavioral/command/command.rs

@@ -6,6 +6,10 @@ pub use copy::CopyCommand;
 pub use cut::CutCommand;
 pub use paste::PasteCommand;
 
+/// Declares a method for executing (and undoing) a command.
+///
+/// Each command receives an application context to access
+/// visual components (e.g. edit view) and a clipboard.
 pub trait Command {
     fn execute(&mut self, app: &mut cursive::Cursive) -> bool;
     fn undo(&mut self, app: &mut cursive::Cursive);

behavioral/command/main.rs

@@ -8,6 +8,8 @@ use cursive::{
 
 use command::{Command, CopyCommand, CutCommand, PasteCommand};
 
+/// An application context to be passed into visual component callbacks.
+/// It contains a clipboard and a history of commands to be undone.
 #[derive(Default)]
 struct AppContext {
     clipboard: String,
@@ -31,6 +33,7 @@ fn main() {
     app.run();
 }
 
+/// Executes a command and then pushes it to a history array.
 fn execute(app: &mut Cursive, mut command: impl Command + 'static) {
     if command.execute(app) {
         app.with_user_data(|context: &mut AppContext| {
@@ -39,6 +42,7 @@ fn execute(app: &mut Cursive, mut command: impl Command + 'static) {
     }
 }
 
+/// Pops the last command and executes an undo action.
 fn undo(app: &mut Cursive) {
     let mut context = app.take_user_data::<AppContext>().unwrap();
     if let Some(mut command) = context.history.pop() {