From 2d8ff27574b9d81868235da3ab1850f204c524d6 Mon Sep 17 00:00:00 2001
From: "John Ankarstr\\xf6m" <john@ankarstrom.se>
Date: Thu, 3 Jun 2021 15:10:36 +0200
Subject: xbattext.ms: Finish source code documentation

---
 xbattext.ms | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 75 insertions(+), 7 deletions(-)

diff --git a/xbattext.ms b/xbattext.ms
index 8166f7d..c54f74c 100644
--- a/xbattext.ms
+++ b/xbattext.ms
@@ -36,7 +36,7 @@ http://git.\:ankarstrom.se/re/.
 .I Xm/Label.h
 contains the definitions for Motif's label widget,
 which is used to display the text.
-That headerf file, in turn, includes
+That file, in turn, includes
 .I X11/Xlib.h
 for us.
 .PP
@@ -56,7 +56,7 @@ which defines how those resources should be retrieved.
 The
 .I res
 structure is going to be filled by the function
-.I XtGetApplicationResources
+.I XtGetApp\%licationResources
 using the information defined in
 .I res_opts .\**
 .FS
@@ -121,7 +121,7 @@ The file descriptor is closed by the kernel when the program exits.
 As mentioned earlier,
 .I XtGetApplicationResources
 uses the
-.I XtResource
+.I XtResour\%ce
 list defined above to fill the
 .I res
 structure with the corresponding resources.
@@ -164,9 +164,9 @@ It returns an
 structure (which must be zeroed first).
 .Re xbattext.c:/^	\/\* put battery status into label/
 .LP
-The battery percentage, contained in the
-.I battery_life
-member, is written to an
+The battery percentage, contained in
+.I info.battery_life ,
+is written to an
 .I XmString ,
 which is a special type of string used by Motif.
 It is associated with a
@@ -188,5 +188,73 @@ value.
 .bp
 .Re xbattext.c:/^	\/\* check .* ac adapter .* plugged in/
 .LP
-\&
+Whenever the value of
+.I info.ac_\:state
+is changed to
+.CW APM_AC_ON ,
+signifying that the AC adapter is plugged in,
+the label widget's foreground color and font is set
+according to the application resources.
+If no
+.I chargeForeground
+resource is defined, the
+.I XtGetApplicationResources
+function sets the color to the integer value zero,
+which is the color black
+(thus, the program cannot differentiate
+between a missing value and a value of
+.I black ).
+The font list, however, is set to null if undefined.
+If it is undefined, the main font list is used.
+.PP
+Note that the
+.I charge
+variable is set in order to prevent these font and color changes
+from unnecessarily  being applied every timeout
+regardless of whether the charging status has changed.
+Note also that any further checks are skipped via a
+.I goto
+statement,
+as the charging indication should override the low battery indication.
 .Re xbattext.c:/^	\/\* check low battery/
+.LP
+The same applies when the program checks whether the battery level is below
+.CW ALERT ,
+which is set to 30 by default.
+.PP
+If, after being below the threshold, the battery level rises above it,
+the color and font are reset to their default values.
+.bp
+.Re xbattext.c:/^	\/\* check .* ac adapter .* plugged out/
+.LP
+After the low battery checks,
+the program checks whether the AC adapter has been plugged out.
+While the low battery indication should not be overriden
+by a return to a normal, non-charging state,
+it is important that the
+.I charge
+variable is updated to reflect the state.
+.PP
+The value of the
+.I i
+counter is inspected to see whether the low battery checks above
+have triggered any color or font changes.
+If they haven't, the color and font are reset to their default values,
+signifying a neither charging nor low battery.
+.Re xbattext.c:/^set:/
+.LP
+Finally, the values collected in
+.I wargs
+are associated with the label widget through the
+.I XtSetValues
+function.
+The
+.I XmString
+is freed,
+as a new one will be created on the next call to
+.I update ,
+which at the end is registered through the
+.I Xt\%AppAddTimeOut
+function to occur in
+.CW INTERVAL
+seconds.
-- 
cgit v1.2.3