[fractal/fractal-next] Improve doc comments

[Julian Sparber <jsparber src gnome org>]

commit fcf41eed04b703e12874c49de450879163c238c3
Author: Kai A. Hiller <V02460 gmail com>
Date:   Thu Aug 5 13:27:03 2021 +0200

    Improve doc comments

 src/components/avatar.rs             | 2 +-
 src/components/context_menu_bin.rs   | 2 +-
 src/components/label_with_widgets.rs | 9 +++++----
 src/components/pill.rs               | 2 +-
 src/components/spinner_button.rs     | 2 +-
 src/error.rs                         | 2 +-
 src/session/avatar.rs                | 2 +-
 src/session/room/event.rs            | 2 +-
 src/session/room/item.rs             | 5 +++--
 src/session/room/room.rs             | 3 +++
 src/session/room/timeline.rs         | 8 ++++++++
 src/session/room_list.rs             | 9 +++++++++
 src/session/sidebar/category.rs      | 3 +++
 src/session/sidebar/entry.rs         | 4 ++++
 src/session/sidebar/item_list.rs     | 4 ++++
 src/session/user.rs                  | 2 +-
 16 files changed, 47 insertions(+), 14 deletions(-)
---
diff --git a/src/components/avatar.rs b/src/components/avatar.rs
index fe804079..848bd76b 100644
--- a/src/components/avatar.rs
+++ b/src/components/avatar.rs
@@ -95,11 +95,11 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A widget displaying an `Avatar` for a `Room` or `User`.
     pub struct Avatar(ObjectSubclass<imp::Avatar>)
         @extends gtk::Widget, adw::Bin, @implements gtk::Accessible;
 }
 
-/// A widget displaying an `Avatar` for a `Room` or `User`
 impl Avatar {
     pub fn new() -> Self {
         glib::Object::new(&[]).expect("Failed to create Avatar")
diff --git a/src/components/context_menu_bin.rs b/src/components/context_menu_bin.rs
index f5e1bc0a..2bbf06d1 100644
--- a/src/components/context_menu_bin.rs
+++ b/src/components/context_menu_bin.rs
@@ -136,11 +136,11 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A Bin widget that adds a context menu.
     pub struct ContextMenuBin(ObjectSubclass<imp::ContextMenuBin>)
         @extends gtk::Widget, adw::Bin, @implements gtk::Accessible;
 }
 
-/// A Bin widget that adds a context menu
 impl ContextMenuBin {
     pub fn new() -> Self {
         glib::Object::new(&[]).expect("Failed to create ContextMenuBin")
diff --git a/src/components/label_with_widgets.rs b/src/components/label_with_widgets.rs
index 2bced280..7c8e694d 100644
--- a/src/components/label_with_widgets.rs
+++ b/src/components/label_with_widgets.rs
@@ -171,13 +171,14 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A Label that can have multiple widgets placed inside the text.
+    ///
+    /// By default the string "<widget>" will be used as location to place the
+    /// child widgets. You can set your own placeholder if you need.
     pub struct LabelWithWidgets(ObjectSubclass<imp::LabelWithWidgets>)
         @extends gtk::Widget, @implements gtk::Accessible, gtk::Buildable;
 }
-/// A Label that can have multiple widgets placed inside the text.
-///
-/// By default the string "<widget>" will be used as location to place the child
-/// widgets. You can set your own placeholder if you need.
+
 impl LabelWithWidgets {
     pub fn new<P: IsA<gtk::Widget>>(label: &str, widgets: Vec<P>) -> Self {
         let obj: Self =
diff --git a/src/components/pill.rs b/src/components/pill.rs
index 3bc98bce..5f3593f0 100644
--- a/src/components/pill.rs
+++ b/src/components/pill.rs
@@ -94,11 +94,11 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// Inline widget displaying an emphasized `User` or `Room`.
     pub struct Pill(ObjectSubclass<imp::Pill>)
         @extends gtk::Widget, adw::Bin, @implements gtk::Accessible;
 }
 
-/// A widget displaying a `User`
 impl Pill {
     pub fn new() -> Self {
         glib::Object::new(&[]).expect("Failed to create Pill")
diff --git a/src/components/spinner_button.rs b/src/components/spinner_button.rs
index a77687a4..3298a770 100644
--- a/src/components/spinner_button.rs
+++ b/src/components/spinner_button.rs
@@ -88,11 +88,11 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// Button showing a spinner, revealing its label once loaded.
     pub struct SpinnerButton(ObjectSubclass<imp::SpinnerButton>)
         @extends gtk::Widget, gtk::Button, @implements gtk::Accessible, gtk::Actionable;
 }
 
-/// A widget displaying a `User`
 impl SpinnerButton {
     pub fn new() -> Self {
         glib::Object::new(&[]).expect("Failed to create SpinnerButton")
diff --git a/src/error.rs b/src/error.rs
index c4d3e192..4a3ccf6f 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -25,10 +25,10 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// An `Error` that can be shown in the UI.
     pub struct Error(ObjectSubclass<imp::Error>);
 }
 
-/// An `Error` that can be shown in the UI
 impl Error {
     pub fn new<F: Fn(&Self) -> Option<gtk::Widget> + 'static>(error: MatrixError, f: F) -> Self {
         let obj: Self = glib::Object::new(&[]).expect("Failed to create Error");
diff --git a/src/session/avatar.rs b/src/session/avatar.rs
index c864f7d9..63b4331c 100644
--- a/src/session/avatar.rs
+++ b/src/session/avatar.rs
@@ -113,10 +113,10 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// Object holding information about a User’s or Room’s `Avatar`.
     pub struct Avatar(ObjectSubclass<imp::Avatar>);
 }
 
-/// This an object that holds information about a Users or Rooms `Avatar`
 impl Avatar {
     pub fn new(session: &Session, url: Option<MxcUri>) -> Self {
         glib::Object::new(&[
diff --git a/src/session/room/event.rs b/src/session/room/event.rs
index 4dcfb7a0..a7fef543 100644
--- a/src/session/room/event.rs
+++ b/src/session/room/event.rs
@@ -147,13 +147,13 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// GObject representation of a Matrix room event.
     pub struct Event(ObjectSubclass<imp::Event>);
 }
 
 // TODO:
 // - [ ] implement operations for events: forward, reply, delete...
 
-/// This is the GObject representation of a matrix room event
 impl Event {
     pub fn new(event: SyncRoomEvent, room: &Room) -> Self {
         let event = BoxedSyncRoomEvent(event);
diff --git a/src/session/room/item.rs b/src/session/room/item.rs
index dd695908..446daa5e 100644
--- a/src/session/room/item.rs
+++ b/src/session/room/item.rs
@@ -111,11 +111,12 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A row inside the RoomHistory.
+    ///
+    /// This can be AnySyncRoomEvent, a day divider or new message divider.
     pub struct Item(ObjectSubclass<imp::Item>);
 }
 
-/// This represents any row inside the room history.
-/// This can be AnySyncRoomEvent, a day divider or new message divider.
 impl Item {
     pub fn for_event(event: Event) -> Self {
         let type_ = BoxedItemType(ItemType::Event(event));
diff --git a/src/session/room/room.rs b/src/session/room/room.rs
index 638e14f9..bc85befe 100644
--- a/src/session/room/room.rs
+++ b/src/session/room/room.rs
@@ -217,6 +217,9 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// GObject representation of a Matrix room.
+    ///
+    /// Handles populating the Timeline.
     pub struct Room(ObjectSubclass<imp::Room>);
 }
 
diff --git a/src/session/room/timeline.rs b/src/session/room/timeline.rs
index 43298ad8..83a3568a 100644
--- a/src/session/room/timeline.rs
+++ b/src/session/room/timeline.rs
@@ -96,6 +96,14 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// List of all loaded Events in a room. Implements ListModel.
+    ///
+    /// There is no strict message ordering enforced by the Timeline; events
+    /// will be appended/prepended to existing events in the order they are
+    /// received by the server.
+    ///
+    /// This struct additionally keeps track of pending events that have yet to
+    /// get an event ID assigned from the server.
     pub struct Timeline(ObjectSubclass<imp::Timeline>)
         @implements gio::ListModel;
 }
diff --git a/src/session/room_list.rs b/src/session/room_list.rs
index 0da3b076..fa13c6a0 100644
--- a/src/session/room_list.rs
+++ b/src/session/room_list.rs
@@ -102,6 +102,15 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// List of all joined rooms of the user.
+    ///
+    /// This is the parent ListModel of the sidebar from which all other models
+    /// are derived. If a room is updated, use `room.notify("category")` to fix
+    /// the sorting.
+    ///
+    /// The `RoomList` also takes care of all so called *pending rooms*, i.e.
+    /// rooms the user requested to join, but received no response from the
+    /// server yet.
     pub struct RoomList(ObjectSubclass<imp::RoomList>)
         @implements gio::ListModel;
 }
diff --git a/src/session/sidebar/category.rs b/src/session/sidebar/category.rs
index 4c0d6eb3..3c0fd0d1 100644
--- a/src/session/sidebar/category.rs
+++ b/src/session/sidebar/category.rs
@@ -102,6 +102,9 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A list of Rooms in the same category implementing ListModel.
+    ///
+    /// This struct is used in ItemList for the sidebar.
     pub struct Category(ObjectSubclass<imp::Category>)
         @implements gio::ListModel;
 }
diff --git a/src/session/sidebar/entry.rs b/src/session/sidebar/entry.rs
index 0aea94ad..d98f4527 100644
--- a/src/session/sidebar/entry.rs
+++ b/src/session/sidebar/entry.rs
@@ -87,6 +87,10 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// A top-level row in the sidebar without children.
+    ///
+    /// Entry is supposed to be used in a TreeListModel, but as it does not have
+    /// any children, implementing the ListModel interface is not required.
     pub struct Entry(ObjectSubclass<imp::Entry>);
 }
 
diff --git a/src/session/sidebar/item_list.rs b/src/session/sidebar/item_list.rs
index 1c0675b6..edcd748b 100644
--- a/src/session/sidebar/item_list.rs
+++ b/src/session/sidebar/item_list.rs
@@ -45,6 +45,10 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// Fixed list of all subcomponents in the sidebar.
+    ///
+    /// ItemList implements the ListModel interface and yields the subcomponents
+    /// from the sidebar, namely Entries and Categories.
     pub struct ItemList(ObjectSubclass<imp::ItemList>)
         @implements gio::ListModel;
 }
diff --git a/src/session/user.rs b/src/session/user.rs
index 8045d1a3..cee37ed3 100644
--- a/src/session/user.rs
+++ b/src/session/user.rs
@@ -111,10 +111,10 @@ mod imp {
 }
 
 glib::wrapper! {
+    /// `glib::Object` representation of a Matrix user.
     pub struct User(ObjectSubclass<imp::User>);
 }
 
-/// This is a `glib::Object` representation of matrix users.
 impl User {
     pub fn new(session: &Session, user_id: &UserId) -> Self {
         glib::Object::new(&[("session", session), ("user-id", &user_id.as_str())])