1 files changed, 91 insertions, 3 deletions

diff --git a/src/pm.c b/src/pm.c
index b9d23835..79c8de51 100644
--- a/src/pm.c
+++ b/src/pm.c
@@ -23,6 +23,12 @@ static bool pm_button_press(GtkTreeView *, GdkEventButton *event, gpointer);
 static bool pm_popup_menu(GtkWidget *, gpointer);
 static void pm_menu_activate(GtkWidget *menu_item, gpointer);
 
+/**
+ * Creates the Project Manager pane.
+ * It consists of an entry box and a treeview called 'textadept-pm-entry' and
+ * 'textadept-pm-view' respectively for styling via gtkrc. The treeview model
+ * consists of a gdk-pixbuf for icons and markup text.
+ */
 GtkWidget* pm_create_ui() {
   pm_container = gtk_vbox_new(false, 1);
 
@@ -72,6 +78,14 @@ GtkWidget* pm_create_ui() {
   return pm_container;
 }
 
+/**
+ * Requests contents for a Project Manager parent node being opened.
+ * Since parents have a dummy child by default just to indicate they are indeed
+ * parents, that dummy child is removed now.
+ * @param iter The parent GtkTreeIter.
+ * @param path The parent GtkTreePath.
+ * @see l_pm_get_contents_for
+ */
 void pm_open_parent(GtkTreeIter *iter, GtkTreePath *path) {
   l_pm_get_full_path(path);
   if (l_pm_get_contents_for(NULL, true)) l_pm_populate(iter);
@@ -84,6 +98,12 @@ void pm_open_parent(GtkTreeIter *iter, GtkTreePath *path) {
   g_free(filename);
 }
 
+/**
+ * Removes all Project Manager children from a parent node being closed.
+ * It does add a dummy child by default to indicate the parent is indeed a
+ * parent. It will be removed when the parent is opened.
+ * @param iter The parent GtkTreeIter.
+ */
 void pm_close_parent(GtkTreeIter *iter, GtkTreePath *) {
   GtkTreeIter child;
   gtk_tree_model_iter_nth_child(GTK_TREE_MODEL(pm_store), &child, iter, 0);
@@ -93,6 +113,12 @@ void pm_close_parent(GtkTreeIter *iter, GtkTreePath *) {
   gtk_tree_store_set(pm_store, &child, 1, "\0dummy", -1);
 }
 
+/**
+ * Performs the appropriate action on a selected Project Manager node.
+ * If the node is a collapsed parent, it is expanded; otherwise the parent is
+ * collapsed. If the node is not a parent at all, a Lua action is performed.
+ * @see l_pm_perform_action
+ */
 void pm_activate_selection() {
   GtkTreeIter iter;
   GtkTreePath *path;
@@ -111,10 +137,20 @@ void pm_activate_selection() {
   gtk_tree_path_free(path);
 }
 
+/**
+ * Pops up a context menu for the selected Project Manager node.
+ * @param event The mouse button event.
+ * @see l_pm_popup_context_menu
+ */
 void pm_popup_context_menu(GdkEventButton *event) {
   l_pm_popup_context_menu(event, G_CALLBACK(pm_menu_activate));
 }
 
+/**
+ * Performs a Lua action for a selected Project Manager menu item.
+ * @param menu_item The menu item.
+ * @see l_pm_perform_menu_action
+ */
 void pm_process_selected_menu_item(GtkWidget *menu_item) {
   GtkWidget *label = gtk_bin_get_child(GTK_BIN(menu_item));
   const char *text = gtk_label_get_text(GTK_LABEL(label));
@@ -125,11 +161,23 @@ void pm_process_selected_menu_item(GtkWidget *menu_item) {
   l_pm_perform_menu_action(text);
 }
 
+/**
+ * Toggles the focus between the Project Manager and the current Scintilla
+ * window.
+ */
 void pm_toggle_focus() {
   gtk_widget_grab_focus(
     GTK_WIDGET_HAS_FOCUS(focused_editor) ? pm_entry : focused_editor);
 }
 
+/**
+ * When searching the Project Manager treeview, matches are tree items that
+ * contain the search text as a substring.
+ * @param model The GtkTreeModel for the treeview.
+ * @param col The column number to use for comparing search text to.
+ * @param key The search text.
+ * @param iter The GtkTreeIter for each tree node being compared.
+ */
 static int pm_search_equal_func(GtkTreeModel *model, int col, const char *key,
                                 GtkTreeIter *iter, gpointer) {
   const char *text;
@@ -137,6 +185,12 @@ static int pm_search_equal_func(GtkTreeModel *model, int col, const char *key,
   return strstr(text, key) == NULL; // false is really a match like strcmp
 }
 
+/**
+ * Sorts the Project Manager treeview case sensitively.
+ * @param model The GtkTreeModel for the treeview.
+ * @param a The GtkTreeIter for one tree node being compared.
+ * @param b The GtkTreeIter for the other tree node being compared.
+ */
 static int pm_sort_iter_compare_func(GtkTreeModel *model, GtkTreeIter *a,
                                      GtkTreeIter *b, gpointer) {
   const char *a_text, *b_text;
@@ -149,14 +203,22 @@ static int pm_sort_iter_compare_func(GtkTreeModel *model, GtkTreeIter *a,
 }
 
 // Signals
+
+/**
+ * Signal for the activation of the Project Manager entry.
+ * Requests contents for the treeview.
+ * @see l_pm_get_contents_for
+ */
 static void pm_entry_activated(GtkWidget *widget, gpointer) {
   const char *entry_text = gtk_entry_get_text(GTK_ENTRY(widget));
   if (l_pm_get_contents_for(entry_text)) l_pm_populate();
 }
 
-/** Project manager key events.
- *  Ctrl+Tab - Refocuses the Scintilla view.
- *  Escape - Refocuses the Scintilla view.
+/**
+ * Signal for a Project Manager keypress.
+ * Currently handled keypresses:
+ *   - Ctrl+Tab - Refocuses the Scintilla view.
+ *   - Escape - Refocuses the Scintilla view.
  */
 static bool pm_keypress(GtkWidget *, GdkEventKey *event, gpointer) {
   if (event->keyval == 0xff09 && event->state == GDK_CONTROL_MASK ||
@@ -166,30 +228,56 @@ static bool pm_keypress(GtkWidget *, GdkEventKey *event, gpointer) {
   } else return false;
 }
 
+/**
+ * Signal for a Project Manager parent expansion.
+ * @see pm_open_parent
+ */
 static void pm_row_expanded(GtkTreeView *, GtkTreeIter *iter,
                             GtkTreePath *path, gpointer) {
   pm_open_parent(iter, path);
 }
 
+/**
+ * Signal for a Project Manager parent collapse.
+ * @see pm_close_parent
+ */
 static void pm_row_collapsed(GtkTreeView *, GtkTreeIter *iter,
                              GtkTreePath *path, gpointer) {
   pm_close_parent(iter, path);
 }
 
+/**
+ * Signal for the activation of a Project Manager node.
+ * @see pm_activate_selection
+ */
 static void pm_row_activated(GtkTreeView *, GtkTreePath *, GtkTreeViewColumn *,
                              gpointer) {
   pm_activate_selection();
 }
 
+/**
+ * Signal for a Project Manager mouse click.
+ * If it is a right-click, popup a context menu for the selected node.
+ * @see pm_popup_context_menu
+ */
 static bool pm_button_press(GtkTreeView *, GdkEventButton *event, gpointer) {
   if (event->type != GDK_BUTTON_PRESS || event->button != 3) return false;
   pm_popup_context_menu(event); return true;
 }
 
+/**
+ * Signal for popping up a Project Manager context menu.
+ * Typically Shift+F10 activates this event.
+ * @see pm_popup_context_menu
+ */
 static bool pm_popup_menu(GtkWidget *, gpointer) {
   pm_popup_context_menu(NULL); return true;
 }
 
+/**
+ * Signal for a selected Project Manager menu item.
+ * @see pm_process_selected_menu_item
+ */
 static void pm_menu_activate(GtkWidget *menu_item, gpointer) {
   pm_process_selected_menu_item(menu_item);
 }