From 01b950a8f719068508a245e9ee6b3d1b1fafe056 Mon Sep 17 00:00:00 2001
From: Hiltjo Posthuma <hiltjo@codemadness.org>
Date: Fri, 4 Feb 2022 20:18:35 +0100
Subject: improve some code comments

---
 sfeed.c        | 12 +++++++-----
 sfeed_curses.c | 13 +++++++------
 util.c         |  4 +++-
 3 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/sfeed.c b/sfeed.c
index 6b4a423..126c685 100644
--- a/sfeed.c
+++ b/sfeed.c
@@ -360,6 +360,7 @@ string_print_trimmed(String *s)
 	printtrimmed(s->data);
 }
 
+/* Print each field with trimmed whitespace, separated by '|'. */
 void
 string_print_trimmed_multi(String *s)
 {
@@ -383,7 +384,7 @@ string_print_trimmed_multi(String *s)
 	}
 }
 
-/* print URL, if it's a relative URL then it uses global baseurl */
+/* Print URL, if it's a relative URL then it uses the global `baseurl`. */
 void
 printuri(char *s)
 {
@@ -409,7 +410,7 @@ printuri(char *s)
 	*e = c; /* restore NUL byte to original character */
 }
 
-/* print URL, if it's a relative URL then it uses global baseurl */
+/* Print URL, if it's a relative URL then it uses the global `baseurl`. */
 void
 string_print_uri(String *s)
 {
@@ -419,7 +420,7 @@ string_print_uri(String *s)
 	printuri(s->data);
 }
 
-/* print as UNIX timestamp, print nothing if the parsed time is invalid */
+/* Print as UNIX timestamp, print nothing if the time is empty or invalid. */
 void
 string_print_timestamp(String *s)
 {
@@ -432,6 +433,7 @@ string_print_timestamp(String *s)
 		printf("%lld", t);
 }
 
+/* Convert time fields. Returns a UNIX timestamp. */
 long long
 datetounix(long long year, int mon, int day, int hour, int min, int sec)
 {
@@ -538,6 +540,8 @@ gettzoffset(const char *s)
 	return 0;
 }
 
+/* Parse time string `s` into the UNIX timestamp `tp`.
+   Returns 0 on success or -1 on failure. */
 static int
 parsetime(const char *s, long long *tp)
 {
@@ -799,8 +803,6 @@ xmlattrstart(XMLParser *p, const char *t, size_t tl, const char *n, size_t nl)
 		string_clear(&tmpstr); /* use the last value for multiple attribute values */
 }
 
-/* NOTE: this handler can be called multiple times if the data in this
- *       block is bigger than the buffer. */
 static void
 xmldata(XMLParser *p, const char *s, size_t len)
 {
diff --git a/sfeed_curses.c b/sfeed_curses.c
index 0cd7ebd..d515c4f 100644
--- a/sfeed_curses.c
+++ b/sfeed_curses.c
@@ -203,12 +203,12 @@ ttywrite(const char *s)
 	return write(1, s, strlen(s));
 }
 
-/* hint for compilers and static analyzers that a function exits */
+/* Hint for compilers and static analyzers that a function exits. */
 #ifndef __dead
 #define __dead
 #endif
 
-/* print to stderr, call cleanup() and _exit(). */
+/* Print to stderr, call cleanup() and _exit(). */
 __dead void
 die(const char *fmt, ...)
 {
@@ -260,7 +260,7 @@ estrdup(const char *s)
 	return p;
 }
 
-/* wrapper for tparm which allows NULL parameter for str. */
+/* Wrapper for tparm which allows NULL parameter for str. */
 char *
 tparmnull(const char *str, long p1, long p2, long p3, long p4, long p5,
           long p6, long p7, long p8, long p9)
@@ -270,6 +270,7 @@ tparmnull(const char *str, long p1, long p2, long p3, long p4, long p5,
 	return tparm(str, p1, p2, p3, p4, p5, p6, p7, p8, p9);
 }
 
+/* Counts column width of character string. */
 size_t
 colw(const char *s)
 {
@@ -1200,7 +1201,7 @@ updatenewitems(struct feed *f)
 	p = &panes[PaneItems];
 	f->totalnew = 0;
 	for (i = 0; i < p->nrows; i++) {
-		row = &(p->rows[i]); /* do not use pane_row_get */
+		row = &(p->rows[i]); /* do not use pane_row_get() */
 		item = row->data;
 		if (urlfile)
 			item->isnew = urls_isnew(item->matchnew);
@@ -1228,7 +1229,7 @@ feed_load(struct feed *f, FILE *fp)
 	free(p->rows);
 	p->rows = ecalloc(sizeof(p->rows[0]), items.len + 1);
 	for (i = 0; i < items.len; i++)
-		p->rows[i].data = &(items.items[i]); /* do not use pane_row_get */
+		p->rows[i].data = &(items.items[i]); /* do not use pane_row_get() */
 
 	updatenewitems(f);
 
@@ -1844,7 +1845,7 @@ markread(struct pane *p, off_t from, off_t to, int isread)
 			die("popen: %s", cmd);
 
 		for (i = from; i <= to && i < p->nrows; i++) {
-			/* do not use pane_row_get: no need for lazyload */
+			/* do not use pane_row_get(): no need for lazyload */
 			row = &(p->rows[i]);
 			item = row->data;
 			if (item->isnew != isnew) {
diff --git a/util.c b/util.c
index 797e599..f1eff23 100644
--- a/util.c
+++ b/util.c
@@ -66,7 +66,7 @@ strcasestr(const char *h, const char *n)
 	return NULL;
 }
 
-/* check if string has a non-empty scheme / protocol part */
+/* Check if string has a non-empty scheme / protocol part. */
 int
 uri_hasscheme(const char *s)
 {
@@ -79,6 +79,8 @@ uri_hasscheme(const char *s)
 	return (*p == ':' && p != s);
 }
 
+/* Parse URI string `s` into an uri structure `u`.
+   Returns 0 on success or -1 on failure */
 int
 uri_parse(const char *s, struct uri *u)
 {
-- 
cgit v1.2.3