From eb981f9f2b21d6226db55a14a8d54b9dd8257403 Mon Sep 17 00:00:00 2001
From: Lynne <lynne@bune.city>
Date: Sun, 6 Sep 2020 20:35:37 +1000
Subject: [PATCH] better documentation

---
 MainWindow.cs | 62 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 3 deletions(-)

diff --git a/MainWindow.cs b/MainWindow.cs
index 542e2fe..ba4d683 100755
--- a/MainWindow.cs
+++ b/MainWindow.cs
@@ -184,6 +184,11 @@ namespace Buypeeb {
 
 		// general behaviour
 
+		/// <summary>
+		/// gets the path and iter for a given item id.
+		/// </summary>
+		/// <param name="id">the item id to find in the treeview</param>
+		/// <returns>a tuple of (TreePath, TreeIter)</returns>
 		private (TreePath path, TreeIter iter) GetRow(string id) {
 			// TODO: surely there's a better way to do this
 			TreeIter iter;
@@ -204,6 +209,9 @@ namespace Buypeeb {
 			return (null, iter);
 		}
 
+		/// <summary>
+		/// saves the settings to userdata.json.
+		/// </summary>
 		private void SaveSettings() {
 			string j = JsonSerializer.Serialize(this.settings, this.jsonOptions);
 			string p = System.IO.Path.Combine(this.location, "userdata.json");
@@ -218,6 +226,10 @@ namespace Buypeeb {
 
 		}
 
+		/// <summary>
+		/// updates the item with the given id. this method blocks and is intended to be run from a task.
+		/// </summary>
+		/// <param name="id">the id of the item to update</param>
 		private void UpdateThread(string id) {
 			var item = this.settings.watchlist[id];
 			// Console.WriteLine($"Updating {id}...");
@@ -256,9 +268,10 @@ namespace Buypeeb {
 			// Console.WriteLine($"{id} updated.");
 		}
 
+		/// <summary>
+		/// recursively processes the update queue. this is a blocking function.
+		/// </summary>
 		private void ProcessUpdateQueue() {
-			// recursively process the updatequeue
-			// this is a BLOCKING FUNCTION
 			this.queueActive = true;
 			this.UpdateItem(this.updateQueue.Dequeue());
 			if (this.updateQueue.TryPeek(out string _)) {
@@ -269,6 +282,11 @@ namespace Buypeeb {
 			}
 		}
 
+		/// <summary>
+		/// updates an item with the given id with a new task.
+		/// </summary>
+		/// <param name="id">the id of the task to update</param>
+		/// <param name="renderListWhenDone">whether or not to call this.RenderList() after updating the item</param>
 		private void UpdateItem(string id, bool renderListWhenDone = false) {
 			var item = this.settings.watchlist[id];
 			if (item.updatedRecently) {
@@ -291,6 +309,9 @@ namespace Buypeeb {
 			});
 		}
 
+		/// <summary>
+		/// add every item in the watchlist to the update queue. if the update queue is already being processed (this.queueActive), this will do nothing.
+		/// </summary>
 		private void UpdateItems() {
 			if (this.queueActive) {
 				return;
@@ -318,6 +339,9 @@ namespace Buypeeb {
 
 		}
 
+		/// <summary>
+		/// updates the selection view, displaying the id, name, etc. for the currently selected item.
+		/// </summary>
 		private void UpdateSelectionView() {
 			// get the currently selected item
 			var item = this.selectedItem;
@@ -359,6 +383,11 @@ namespace Buypeeb {
 			(this.builder.GetObject("ButtonSelectedFavourite") as ToggleButton).Active = item.favourite;
 
 		}
+
+		/// <summary>
+		/// opens a URL in the user's browser.
+		/// </summary>
+		/// <param name="url">the url to open</param>
 		private void OpenUrl(string url) {
 			// https://github.com/dotnet/runtime/issues/17938
 			if (Environment.OSVersion.Platform == PlatformID.Win32NT) {
@@ -374,6 +403,12 @@ namespace Buypeeb {
 			}
 		}
 
+		/// <summary>
+		/// a simple MessageDialog constructor.
+		/// </summary>
+		/// <param name="message">the MessageDialog's format</param>
+		/// <param name="buttonsType">the MessageDialog's bt</param>
+		/// <returns></returns>
 		private MessageDialog MsgBox(string message, ButtonsType buttonsType = ButtonsType.OkCancel) {
 			var md = new MessageDialog(
 				parent_window: this,
@@ -390,7 +425,13 @@ namespace Buypeeb {
 			return md;
 		}
 
-		// show a simple entry dialogue that allows the user to enter text and either cancel or submit it
+		/// <summary>
+		/// show a simple entry dialogue that allows the user to enter text and either cancel or submit it.
+		/// </summary>
+		/// <param name="title">the title of the entry dialogue</param>
+		/// <param name="message">the prompt that should be presented to the user</param>
+		/// <param name="prefill">a string to prefill the input box with</param>
+		/// <returns></returns>
 		private (Boolean accepted, string response) EntryDialogue(string title = "Buypeeb", string message = "Hi there!", string prefill = null) {
 			Dialog ed = new Dialog(
 				title: title,
@@ -426,6 +467,10 @@ namespace Buypeeb {
 			return (accepted == ResponseType.Ok, response);
 		}
 
+		/// <summary>
+		/// gets the sort type selected by the user - "NameDescending", "EndingAscending", etc.
+		/// </summary>
+		/// <returns>the id of the radiobutton without the "Sort" prefix</returns>
 		private string GetSortType() {
 			foreach (var name in new List<string> { "NameDescending", "NameAscending", "PriceDescending", "PriceAscending", "EndingDescending", "EndingAscending" }) {
 				var radio = (RadioMenuItem)this.builder.GetObject($"Sort{name}");
@@ -437,6 +482,9 @@ namespace Buypeeb {
 			return "NameAscending";
 		}
 
+		/// <summary>
+		/// clears the treeview's liststore and adds everything in the watchlist to it, obeying sort order. tries to reselect the item that the user had selected, if possible.
+		/// </summary>
 		private void RenderList() {
 			string id = null;
 			if (this.selectedItem != null) {
@@ -777,6 +825,10 @@ namespace Buypeeb {
 
 		// timers
 
+		/// <summary>
+		/// updates the end time displayed in the selection box. runs every second to update the countdown timer.
+		/// </summary>
+		/// <returns>true</returns>
 		private bool UpdateSelectionEndTime() {
 			if (!this.selectionViewBox.IsSensitive) {
 				return true;
@@ -809,6 +861,10 @@ namespace Buypeeb {
 			return true;
 		}
 
+		/// <summary>
+		/// updates all items that need updating. runs every ten seconds.
+		/// </summary>
+		/// <returns>true</returns>
 		private bool AutoUpdateItems() {
 			if (this.queueActive) {
 				// don't autoupdate if the queue is active