From 89d0274c802aa1fa2c7edc0ffe73cec2cf286f08 Mon Sep 17 00:00:00 2001
From: Marrub <marrub.xz@gmail.com>
Date: Wed, 3 Apr 2019 21:43:37 -0400
Subject: [PATCH] better documentation

---
 source/tycho/interfaces/cairo.rs  |  1 +
 source/tycho/interfaces/editor.rs | 21 +++++++++++++--------
 source/tycho/main.rs              |  5 +++++
 3 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/source/tycho/interfaces/cairo.rs b/source/tycho/interfaces/cairo.rs
index 0b806b5..ceacafb 100644
--- a/source/tycho/interfaces/cairo.rs
+++ b/source/tycho/interfaces/cairo.rs
@@ -43,6 +43,7 @@ impl CrDrawArea
          pango_font_description_free(dsc);
          pan
       };
+
       let pan = Refc::new(pan);
 
       CrDrawArea{ctx, pan, w: w as draw::Coord, h: h as draw::Coord}
diff --git a/source/tycho/interfaces/editor.rs b/source/tycho/interfaces/editor.rs
index 73863c8..acc298b 100644
--- a/source/tycho/interfaces/editor.rs
+++ b/source/tycho/interfaces/editor.rs
@@ -5,6 +5,7 @@ use gobject_sys::*;
 use gtk_sys::*;
 use maraiah::{durandal::ffi, marathon::map, rozinante::editor};
 
+// Iterates over each flag widget with its respective ordered flag object.
 fn each_flag<T, F>(buttons: &[PropFlag], ordering: &[T], mut f: F)
    where F: FnMut(&PropFlag, &T)
 {
@@ -13,11 +14,14 @@ fn each_flag<T, F>(buttons: &[PropFlag], ordering: &[T], mut f: F)
    }
 }
 
-fn refresh_flags<T, F>(mut f: F) -> impl FnMut(&PropFlag, &T)
+// Creates a closure which sets if a button is toggled.
+fn r_flg<T, F>(mut f: F) -> impl FnMut(&PropFlag, &T)
    where F: FnMut(&T) -> bool
 {
    move |flg, ord| {
       unsafe {
+         // we have to block the signal handler so that it doesn't cause an
+         // infinite recursion of updating
          g_signal_handler_block(*flg.w as _, flg.h);
 
          gtk_toggle_button_set_active(*flg.w, f(ord).into());
@@ -27,7 +31,8 @@ fn refresh_flags<T, F>(mut f: F) -> impl FnMut(&PropFlag, &T)
    }
 }
 
-fn set_flags<T, F>(mut f: F) -> impl FnMut(&PropFlag, &T)
+// Creates a closure which checks if a button is toggled.
+fn s_flg<T, F>(mut f: F) -> impl FnMut(&PropFlag, &T)
    where F: FnMut(&T, bool)
 {
    move |flg, ord| f(ord, unsafe {gtk_toggle_button_get_active(*flg.w)} != 0)
@@ -55,9 +60,9 @@ impl MapEditor
    {
       let inf = &self.cur_block().info;
 
-      each_flag(&self.fent, &O_ENT, refresh_flags(|&f| inf.entr_flags.contains(f)));
-      each_flag(&self.fenv, &O_ENV, refresh_flags(|&f| inf.envi_flags.contains(f)));
-      each_flag(&self.fmsn, &O_MSN, refresh_flags(|&f| inf.miss_flags.contains(f)));
+      each_flag(&self.fent, &O_ENT, r_flg(|&f| inf.entr_flags.contains(f)));
+      each_flag(&self.fenv, &O_ENV, r_flg(|&f| inf.envi_flags.contains(f)));
+      each_flag(&self.fmsn, &O_MSN, r_flg(|&f| inf.miss_flags.contains(f)));
    }
 
    /// Propagates updated map property information to the editor state.
@@ -66,9 +71,9 @@ impl MapEditor
       let mut blk = self.cur_block().clone();
       let inf = &mut blk.info;
 
-      each_flag(&self.fent, &O_ENT, set_flags(|&f, s| inf.entr_flags.set(f, s)));
-      each_flag(&self.fenv, &O_ENV, set_flags(|&f, s| inf.envi_flags.set(f, s)));
-      each_flag(&self.fmsn, &O_MSN, set_flags(|&f, s| inf.miss_flags.set(f, s)));
+      each_flag(&self.fent, &O_ENT, s_flg(|&f, s| inf.entr_flags.set(f, s)));
+      each_flag(&self.fenv, &O_ENV, s_flg(|&f, s| inf.envi_flags.set(f, s)));
+      each_flag(&self.fmsn, &O_MSN, s_flg(|&f, s| inf.miss_flags.set(f, s)));
 
       self.push_block(blk);
       self.cause_refresh_view();
diff --git a/source/tycho/main.rs b/source/tycho/main.rs
index 6ab3dfa..254d270 100644
--- a/source/tycho/main.rs
+++ b/source/tycho/main.rs
@@ -89,23 +89,28 @@ unsafe fn get_flag_fields(b: &Refc<GtkBuilder>, name: ffi::NT) -> Vec<PropFlag>
    flags
 }
 
+// Connects toggle events to every flag in the map properties window.
 unsafe fn setup_toggles(edit: Rc<MapEditorRef>)
 {
    let mut ed = edit.borrow_mut();
+
    connect_toggle(edit.clone(), ed.fent.iter_mut());
    connect_toggle(edit.clone(), ed.fenv.iter_mut());
    connect_toggle(edit.clone(), ed.fmsn.iter_mut());
 }
 
+// Connects toggle events to each of the widgets in `it`.
 unsafe fn connect_toggle<'a, I>(edit: Rc<MapEditorRef>, it: I)
    where I: Iterator<Item = &'a mut PropFlag>
 {
+   // Callback for when the button is toggled, which causates an update.
    unsafe extern "C" fn c_toggled(_: *mut GtkToggleButton, edit: gpointer)
    {
       let edit = &*(edit as *const MapEditorRef);
       edit.borrow_mut().cause_update_props();
    }
 
+   // go over each widget, set its object and callback handle
    for flg in it {
       let erf = connect_ref(*flg.w, edit.clone());
       flg.h = connect(*flg.w, E_TOGGLE, c_toggled as _, erf);