From 8a7dfcd4eed4a154392cc272b7e7095861c63ee4 Mon Sep 17 00:00:00 2001
From: Manos Pitsidianakis <el13635@mail.ntua.gr>
Date: Mon, 6 Aug 2018 22:20:34 +0300
Subject: Add some documentation

---
 ui/src/components/mail/mod.rs |  1 +
 ui/src/execute/actions.rs     |  4 ++++
 ui/src/lib.rs                 |  4 ++++
 ui/src/state.rs               | 19 ++++++++++++++++++-
 4 files changed, 27 insertions(+), 1 deletion(-)

(limited to 'ui')

diff --git a/ui/src/components/mail/mod.rs b/ui/src/components/mail/mod.rs
index 04d785f6..775c4f7b 100644
--- a/ui/src/components/mail/mod.rs
+++ b/ui/src/components/mail/mod.rs
@@ -14,6 +14,7 @@ struct AccountMenuEntry {
     entries: Vec<(usize, Folder)>,
 }
 
+/// The account sidebar.
 #[derive(Debug)]
 pub struct AccountMenu {
     accounts: Vec<AccountMenuEntry>,
diff --git a/ui/src/execute/actions.rs b/ui/src/execute/actions.rs
index f4ccb55e..bf556c4d 100644
--- a/ui/src/execute/actions.rs
+++ b/ui/src/execute/actions.rs
@@ -1,3 +1,7 @@
+/*!
+ * User actions that need to be handled by the UI
+ */
+
 #[derive(Debug)]
 pub enum MailListingAction {
     ToggleThreaded,
diff --git a/ui/src/lib.rs b/ui/src/lib.rs
index 7bd9497d..9d49f4db 100644
--- a/ui/src/lib.rs
+++ b/ui/src/lib.rs
@@ -19,6 +19,10 @@
  * along with meli. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/*!
+ * This library exports the public types and methods of its modules
+ */
+
 extern crate melib;
 extern crate mime_apps;
 extern crate notify_rust;
diff --git a/ui/src/state.rs b/ui/src/state.rs
index bcd9b5af..2a335ede 100644
--- a/ui/src/state.rs
+++ b/ui/src/state.rs
@@ -1,4 +1,5 @@
-/*!
+/*! The application's state.
+
   The UI crate has an Entity-Component-System design. The System part, is also the application's state, so they're both merged in the `State` struct.
 
   `State` owns all the Entities of the UI, which are currently plain Containers for `Component`s. In the application's main event loop, input is handed to the state in the form of `UIEvent` objects which traverse the entity graph. Components decide to handle each input or not.
@@ -158,11 +159,15 @@ impl State<std::io::Stdout> {
         s
     }
 
+    /// If an owned thread returns a `ThreadEvent::ThreadJoin` event to `State` then it must remove
+    /// the thread from its list and `join` it.
     pub fn join(&mut self, id: thread::ThreadId) {
         let handle = self.threads.remove(&id).unwrap();
         handle.join().unwrap();
     }
 
+    /// If startup has finished, inform startup thread that it doesn't need to tick us with startup
+    /// check reminders and let it die.
     pub fn finish_startup(&mut self) {
         // TODO: Encode startup process with the type system if possible
         if self.startup_thread.is_none() {
@@ -173,6 +178,9 @@ impl State<std::io::Stdout> {
             tx.send(true);
         }
     }
+
+    /// Switch back to the terminal's main screen (The command line the user sees before opening
+    /// the application)
     pub fn to_main_screen(&mut self) {
         write!(
             self.stdout(),
@@ -199,6 +207,7 @@ impl State<std::io::Stdout> {
     }
 }
 impl<W: Write> State<W> {
+    /// On `SIGWNICH` the `State` redraws itself according to the new terminal size.
     pub fn update_size(&mut self) {
         let termsize = termion::terminal_size().ok();
         let termcols = termsize.map(|(w, _)| w);
@@ -221,6 +230,7 @@ impl<W: Write> State<W> {
         });
     }
 
+    /// Force a redraw for all dirty components.
     pub fn redraw(&mut self) {
         for i in 0..self.entities.len() {
             self.draw_entity(i);
@@ -231,6 +241,8 @@ impl<W: Write> State<W> {
             self.draw_area(a);
         }
     }
+
+    /// Draw only a specific `area` on the screen.
     fn draw_area(&mut self, area: Area) {
         let upper_left = upper_left!(area);
         let bottom_right = bottom_right!(area);
@@ -269,6 +281,8 @@ impl<W: Write> State<W> {
         }
         self.flush();
     }
+
+    /// Draw the entire screen from scratch.
     pub fn render(&mut self) {
         self.update_size();
 
@@ -306,6 +320,7 @@ impl<W: Write> State<W> {
         }
     }
 
+    /// The application's main loop sends `UIEvents` to state via this method.
     pub fn rcv_event(&mut self, event: UIEvent) {
         match event.event_type {
             // Command type is handled only by State.
@@ -383,6 +398,8 @@ impl<W: Write> State<W> {
             });
         }
     }
+
+    
     pub fn try_wait_on_child(&mut self) -> Option<bool> {
         if {
             match self.child {
-- 
cgit v1.2.3