From 1ddf72d8a4fc21b6957aef1f67ac3e265c351fc9 Mon Sep 17 00:00:00 2001
From: Werner Kroneman <werner@wernerkroneman.nl>
Date: Sun, 10 Dec 2023 15:27:50 +0100
Subject: [PATCH] Improve code readability with comments and annotations.

---
 src/widgets/room_join_widget.rs |  4 ++++
 src/widgets/room_list.rs        | 18 ++++++++++++++++--
 src/widgets/room_view.rs        | 11 +++++++++++
 src/widgets/send_message.rs     |  8 ++++++++
 4 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/src/widgets/room_join_widget.rs b/src/widgets/room_join_widget.rs
index 669aaec..230d072 100644
--- a/src/widgets/room_join_widget.rs
+++ b/src/widgets/room_join_widget.rs
@@ -19,11 +19,15 @@ use dioxus::core_macro::Props;
 use dioxus::hooks::use_state;
 use dioxus::prelude::*;
 
+/// The props for the room join widget, including:
+/// * The event handler for when the user clicks the join button, passing in a room name. This name is not validated in any way.
 #[derive(Props)]
 pub struct RoomJoinProps<'a> {
     on_join_room: EventHandler<'a, String>,
 }
 
+/// A simple widget that allows the user to join a room by typing
+/// its name into a text field and clicking a button.
 pub fn RoomJoinWidget<'a>(cx: Scope<'a, RoomJoinProps>) -> Element<'a> {
     let room = use_state(cx, || "".to_owned());
 
diff --git a/src/widgets/room_list.rs b/src/widgets/room_list.rs
index 7efe56b..d42e5a0 100644
--- a/src/widgets/room_list.rs
+++ b/src/widgets/room_list.rs
@@ -19,33 +19,47 @@ use dioxus::core_macro::Props;
 use dioxus::prelude::*;
 use jid::BareJid;
 
+/// The props for the room list widget, including:
+/// * The list of rooms to show.
+/// * The event handler for when the user clicks a room.
+/// * The event handler for when the user clicks the "leave" button for a room.
 #[derive(Props)]
 pub struct RoomListProps<'a> {
-    rooms: Vec<BareJid>,
+    rooms: Vec<BareJid>, // TODO: Should this be a reference of some kind?
     on_room_picked: EventHandler<'a, BareJid>,
     on_room_left: EventHandler<'a, BareJid>,
 }
 
-/// A Dioxus component that renders a list of rooms
+/// A widget that shows a list of rooms known to the client.
+///
+/// It provides an overview of the rooms, and allows the user to
+/// select a room or to leave it.
+///
+/// How "selecting" and "leaving" a room is handled is up to the context.
 pub fn RoomList<'a>(cx: Scope<'a, RoomListProps>) -> Element<'a> {
     render! {
+        // An <ul> with a list of <li> elements, each containing a room name and a button.
         ul {
             list_style: "none",
             flex_grow: 1,
             margin: 0,
             padding: 0,
             for room in cx.props.rooms.iter() {
+                // A single <li> element, containing a room name and a button.
+
                 rsx! { li {
                     display: "flex",
                     flex_direction: "row",
 
                     onclick: |_evt| cx.props.on_room_picked.call(room.to_owned()),
 
+                    // The room name inside a <div>.
                     div {
                         flex_grow: 1,
                         "{room}"
                     }
 
+                    // A button to leave the room.
                     button {
 
                         onclick: |evt| {
diff --git a/src/widgets/room_view.rs b/src/widgets/room_view.rs
index 12dbbf5..cdabd53 100644
--- a/src/widgets/room_view.rs
+++ b/src/widgets/room_view.rs
@@ -22,6 +22,10 @@ use dioxus::hooks::use_state;
 use dioxus::prelude::*;
 use jid::BareJid;
 
+/// The props for the room view widget, including:
+/// * The room identifier (BareJid) to display.
+/// * The list of messages to display.
+/// * The event handler for when the user sends a message.
 #[derive(Props)]
 pub struct RoomViewProps<'a> {
     room: BareJid,
@@ -29,6 +33,7 @@ pub struct RoomViewProps<'a> {
     on_message_sent: EventHandler<'a, String>,
 }
 
+/// A widget that shows a room, including a list of messages and a widget to send new messages.
 pub fn RoomView<'a>(cx: Scope<'a, RoomViewProps>) -> Element<'a> {
     let _message = use_state(cx, || "".to_owned());
 
@@ -39,12 +44,16 @@ pub fn RoomView<'a>(cx: Scope<'a, RoomViewProps>) -> Element<'a> {
             display: "flex",
             background_color: "#166322",
             flex_direction: "column",
+
+            // The room name, as an H2 (H1 is reserved for the app name).
             h2 {
                 margin: 0,
                 padding: 0,
                 border_bottom: "1px solid lightgray",
                 "{cx.props.room}"
             }
+
+            // The list of messages, as an <ul>, where each message is an <li>.
             ul {
                 flex_grow: 1,
                 overflow_y: "scroll",
@@ -54,6 +63,8 @@ pub fn RoomView<'a>(cx: Scope<'a, RoomViewProps>) -> Element<'a> {
                     } }
                 }
             }
+
+            // The widget to compose new messages and send them.
             SendMessage {
                 on_message_sent: |x:String| cx.props.on_message_sent.call(x),
             }
diff --git a/src/widgets/send_message.rs b/src/widgets/send_message.rs
index 3525bc2..4d93b8d 100644
--- a/src/widgets/send_message.rs
+++ b/src/widgets/send_message.rs
@@ -24,13 +24,19 @@ pub struct SendMessageProps<'a> {
     on_message_sent: EventHandler<'a, String>,
 }
 
+/// A simple widget that allows the user to compose a message and a button to send it.
 pub fn SendMessage<'a>(cx: Scope<'a, SendMessageProps>) -> Element<'a> {
+
+    // The message body being written.
     let message = use_state(cx, || "".to_owned());
 
     render! {
         div {
+            class: "send-message-widget",
             display: "flex",
             flex_direction: "row",
+
+            // A non-resizable text area for the message body.
             textarea {
                 resize: "none",
                 flex_grow: 1,
@@ -38,6 +44,8 @@ pub fn SendMessage<'a>(cx: Scope<'a, SendMessageProps>) -> Element<'a> {
                     message.set(evt.value.clone());
                 }
             }
+
+            // A button to send the message.
             button {
                 height: "100%",
                 onclick: move |_| {