From 31ec4c21055d796f3aa2e05020059a85413247a2 Mon Sep 17 00:00:00 2001
From: "John Ankarstr\\xf6m" <john@ankarstrom.se>
Date: Thu, 3 Jun 2021 09:43:22 +0200
Subject: Improve documentation

---
 xbattext.c  |  8 ++++++--
 xbattext.ms | 26 +++++++++++++++++++++++---
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/xbattext.c b/xbattext.c
index 9eecac7..4f56225 100644
--- a/xbattext.c
+++ b/xbattext.c
@@ -126,9 +126,11 @@ update(XtPointer client_data, XtIntervalId *t)
 	sprintf(s, "%d%%", info.battery_life);
 	xms = XmStringCreate(s, XmFONTLIST_DEFAULT_TAG);
 
+	/* set color and font depending on battery status */
 	i = 0;
 	XtSetArg(wargs[i], XmNlabelString, xms); i++;
 
+	/* check if the ac adapter has been plugged in */
 	if (!charge && info.ac_state == APM_AC_ON) {
 		charge = 1;
 		XtSetArg(wargs[i], XtNforeground, res.charge_foreground);
@@ -140,9 +142,10 @@ update(XtPointer client_data, XtIntervalId *t)
 			XtSetArg(wargs[i], XmNfontList, res.font_list);
 			i++;
 		}
-		goto set; /* skip alert */
+		goto set; /* skip further checks */
 	}
 
+	/* check low battery */
 #ifdef ALERT
 	if (!alert && info.battery_life < ALERT) {
 		alert = 1;
@@ -163,9 +166,10 @@ update(XtPointer client_data, XtIntervalId *t)
 	}
 #endif
 
+	/* check if the ac adapter has been plugged out */
 	if (charge && info.ac_state != APM_AC_ON) {
 		charge = 0;
-		if (i > 1) goto set; /* skip if alert already set */
+		if (i > 1) goto set; /* don't overwrite alert */
 		XtSetArg(wargs[i], XtNforeground, res.foreground);
 		i++;
 		if (res.font_list != NULL) {
diff --git a/xbattext.ms b/xbattext.ms
index 06c1269..8166f7d 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -1,4 +1,7 @@
 .so /home/john/prj/re/re.tmac
+.de Q
+\\$3\(lq\\$1\(rq\\$2
+..
 .TL
 .BI xbattext ,
 an X11 battery monitor for NetBSD
@@ -166,7 +169,24 @@ The battery percentage, contained in the
 member, is written to an
 .I XmString ,
 which is a special type of string used by Motif.
-It is associated with tag,
+It is associated with a
+.Q "font list element tag" ,
 which contains information about the visual characteristics of the text.
-To begin with, the string is set to use the default tag.
-.Re xbattext.c:/^	i = 0;/
+We just use the default.
+.Re xbattext.c:/^	\/\* set color and font/
+.LP
+In the following section, the
+.I wargs
+array mentioned earlier is filled with a number of arguments
+that determine the visual appearance of the label widget.
+The number of arguments set is kept track of in the
+.I i
+variable.
+To begin with, the widget's label string is set to the previously defined
+.I XmString
+value.
+.bp
+.Re xbattext.c:/^	\/\* check .* ac adapter .* plugged in/
+.LP
+\&
+.Re xbattext.c:/^	\/\* check low battery/
-- 
cgit v1.2.3