From 71e164ed30d504bbc7e8f3caa8eea84e7ecdcf77 Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@pond.sub.org>
Date: Mon, 13 Jun 2005 19:02:49 +0000
Subject: [PATCH] Document, in particular use of UTF-8.  Simplify code in a
 couple of places, but no functional changes.

---
 include/misc.h            |   3 +-
 include/player.h          |   4 +-
 include/prototypes.h      |  30 +++----
 src/lib/commands/flash.c  |  17 ++--
 src/lib/commands/play.c   |   2 +-
 src/lib/commands/rea.c    |   2 +-
 src/lib/commands/shut.c   |   4 +-
 src/lib/commands/tele.c   |   6 +-
 src/lib/commands/turn.c   |   2 +-
 src/lib/gen/getstring.c   |   8 +-
 src/lib/gen/parse.c       |   7 +-
 src/lib/player/dispatch.c |   7 +-
 src/lib/player/empdis.c   |   2 +-
 src/lib/player/player.c   |  14 +--
 src/lib/subs/getele.c     |   5 +-
 src/lib/subs/pr.c         | 185 +++++++++++++++++++++++++++++---------
 src/lib/subs/wu.c         |   6 +-
 17 files changed, 199 insertions(+), 105 deletions(-)

diff --git a/include/misc.h b/include/misc.h
index a6d4e2d25..a3de937f0 100644
--- a/include/misc.h
+++ b/include/misc.h
@@ -144,8 +144,7 @@ extern s_char *iesplur(int n);
 extern s_char *plur(int n, s_char *no, s_char *yes);
 extern char *getstarg(char *input, char *prompt, char buf[]);
 extern char *getstring(char *prompt, char buf[]);
-extern char *ugetstring(char *prompt, char buf[]
-			/* buf is message text */);
+extern char *ugetstring(char *prompt, char buf[]);
              
 extern s_char *prbuf(s_char *format, ...)
     ATTRIBUTE((format (printf, 1, 2)));
diff --git a/include/player.h b/include/player.h
index dbf0904f2..a7807ae0b 100644
--- a/include/player.h
+++ b/include/player.h
@@ -58,8 +58,8 @@ struct player {
     struct cmndstr *command;
     struct iop *iop;
     char combuf[1024];		/* command input buffer, UTF-8 */
-    s_char *argp[128];
-    s_char *condarg;
+    char *argp[128];		/* arguments, ASCII */
+    char *condarg;		/* conditional, ASCII */
     time_t lasttime;
     int ncomstat;
     int minleft;
diff --git a/include/prototypes.h b/include/prototypes.h
index 91699e4b5..788d5943f 100644
--- a/include/prototypes.h
+++ b/include/prototypes.h
@@ -63,8 +63,7 @@ extern void finish_server(void);
  */
 extern int check_market(void);
 extern void set_coastal(struct sctstr *);
-extern int sendmessage(struct natstr *, struct natstr *, char *message
-		       /* message is message text */, int);
+extern int sendmessage(struct natstr *, struct natstr *, char *message, int);
 extern void gift(int, int, s_char *, int, s_char *);
 extern int display_mark(i_type, int);
 extern int want_to_abandon(struct sctstr *, i_type, int, struct lndstr *);
@@ -592,32 +591,29 @@ extern int pln_identchance(struct plnstr *, int, int);
 extern void pln_set_tech(struct plnstr *, int);
 /* pr.c */
 extern void pr(char *, ...) ATTRIBUTE((format (printf, 1, 2)));
-extern void uprnf(char *buf /* buf is message text */);
-extern void pr_id(struct player *, int, s_char *, ...)
+extern void uprnf(char *buf);
+extern void pr_id(struct player *, int, char *, ...)
 		ATTRIBUTE((format (printf, 3, 4)));
-extern void pr_flash(struct player *, char *format
-		     /* format is message text */, ...)
+extern void pr_flash(struct player *, char *format, ...)
 		ATTRIBUTE((format (printf, 2, 3)));
-extern void pr_inform(struct player *, s_char *, ...)
+extern void pr_inform(struct player *, char *, ...)
 		ATTRIBUTE((format (printf, 2, 3)));
-extern void pr_wall(s_char *, ...)
+extern void pr_wall(char *, ...)
 		ATTRIBUTE((format (printf, 1, 2)));
 extern void pr_player(struct player *pl, int id, s_char *buf);
-extern void upr_player(struct player *pl, int id, char *buf
-		                  /* buf is message text */);
+extern void upr_player(struct player *pl, int id, char *buf);
 extern void pr_hilite(s_char *buf);
-extern void prredir(s_char *redir);
-extern void prexec(s_char *file);
+extern void prredir(char *redir);
+extern void prexec(char *file);
 extern void prprompt(int min, int btu);
 extern int prmptrd(char *prompt, char *str, int size);
-extern int uprmptrd(char *prompt, char *str /* str is message text */,
-		    int size);
+extern int uprmptrd(char *prompt, char *str, int size);
 extern void prdate(void);
-extern void prxy(s_char *format, coord x, coord y, natid country);
-extern void PR(int, s_char *, ...) ATTRIBUTE((format (printf, 2, 3)));
+extern void prxy(char *format, coord x, coord y, natid country);
+extern void PR(int, char *, ...) ATTRIBUTE((format (printf, 2, 3)));
 extern void PRdate(natid cn);
 extern void pr_beep(void);
-extern void mpr(int, s_char *, ...) ATTRIBUTE((format (printf, 2, 3)));
+extern void mpr(int, char *, ...) ATTRIBUTE((format (printf, 2, 3)));
 extern size_t copy_ascii_no_funny(char *, char *);
 extern size_t copy_utf8_no_funny(char *, char *);
 extern size_t copy_utf8_to_ascii_no_funny(char *, char *);
diff --git a/src/lib/commands/flash.c b/src/lib/commands/flash.c
index f7f37eb43..e4103ff0a 100644
--- a/src/lib/commands/flash.c
+++ b/src/lib/commands/flash.c
@@ -74,7 +74,7 @@ flash(void)
     }
 
     if (player->argp[2]) {
-	for (sp = &player->combuf[0]; *sp && *sp != ' '; ++sp) ;
+	for (sp = player->combuf; *sp && *sp != ' '; ++sp) ;
 	for (++sp; *sp && *sp != ' '; ++sp) ;
 	buf[0] = ':';
 	if (player->flags & PF_UTF8)
@@ -103,7 +103,7 @@ wall(void)
 
     us = getnatp(player->cnum);
     if (player->argp[1]) {
-	for (sp = &player->combuf[0]; *sp && *sp != ' '; ++sp) ;
+	for (sp = player->combuf; *sp && *sp != ' '; ++sp) ;
 	buf[0] = ':';
 	if (player->flags & PF_UTF8)
 	    strcpy(buf+1, sp);
@@ -122,23 +122,28 @@ wall(void)
     return RET_OK;
 }
 
+/*
+ * Send flash message MESSAGE from US to TO.
+ * MESSAGE is UTF-8.  Long messages are broken into several parts.
+ * A header identifying US is prepended to each part.  The first
+ * header is more verbose if ONESHOT.
+ */
 int
-sendmessage(struct natstr *us, struct natstr *to, char *message
-	    /* message is message text */, int oneshot)
+sendmessage(struct natstr *us, struct natstr *to, char *message, int oneshot)
 {
     struct player *other;
     struct tm *tm;
     time_t now;
     int sent = 0;
     struct natstr *wto;
-    char c; /* c is message text */
+    char c;
     int pos;
 
     pos = ufindpfx(message, 60);
     c = message[pos];
     if (c)
         message[pos] = '\0';
-    
+
     time(&now);
     tm = localtime(&now);
     for (other = player_next(0); other != 0; other = player_next(other)) {
diff --git a/src/lib/commands/play.c b/src/lib/commands/play.c
index 0350919b5..51d8b3263 100644
--- a/src/lib/commands/play.c
+++ b/src/lib/commands/play.c
@@ -70,7 +70,7 @@ static int
 play_list(struct player *joe)
 {
     time_t now;
-    char com[1 + 6*20 + 2];	/* user text */
+    char com[1 + 6*20 + 2];	/* UTF-8 */
     struct natstr *natp;
     struct natstr *us;
     int n;
diff --git a/src/lib/commands/rea.c b/src/lib/commands/rea.c
index ccf405c35..3d942d22f 100644
--- a/src/lib/commands/rea.c
+++ b/src/lib/commands/rea.c
@@ -64,7 +64,7 @@ rea(void)
     int size;
     unsigned int nbytes;
     char buf[1024];
-    char msgbuf[4096];		/* message text */
+    char msgbuf[4096];		/* UTF-8 */
     int lasttype;
     int lastcnum;
     time_t lastdate;
diff --git a/src/lib/commands/shut.c b/src/lib/commands/shut.c
index 20073ee51..94cbc4cd7 100644
--- a/src/lib/commands/shut.c
+++ b/src/lib/commands/shut.c
@@ -47,9 +47,9 @@ shut(void)
     int shutdown_minutes;
     int shutdown_was_pending;
     char buf[1024];
-    s_char msgbuf[100];		/* user text */
+    char msgbuf[100];
     struct natstr *us;
-    s_char *p;
+    char *p;
 
     if (update_pending) {
 	pr("Update is pending\n");
diff --git a/src/lib/commands/tele.c b/src/lib/commands/tele.c
index a0a13feb2..a8da53fd6 100644
--- a/src/lib/commands/tele.c
+++ b/src/lib/commands/tele.c
@@ -46,8 +46,7 @@ tele(void)
 {
     natid to;
     struct natstr *natp;
-    int teltype;
-    s_char buf[MAXTELSIZE + 1];
+    char buf[MAXTELSIZE + 1];	/* UTF-8 */
     int n;
 
     natp = getnatp(player->cnum);
@@ -113,8 +112,7 @@ tele(void)
 		pr("%s is rejecting your telegrams.\n", cname(to));
 		return RET_SYN;
 	    }
-	    teltype = /* player->god ? TEL_BULLETIN : */ TEL_NORM;
-	    if (typed_wu(player->cnum, to, buf, teltype) < 0) {
+	    if (typed_wu(player->cnum, to, buf, TEL_NORM) < 0) {
 		logerror("tele: typed_wu failed to #%d", n);
 		return RET_FAIL;
 	    }
diff --git a/src/lib/commands/turn.c b/src/lib/commands/turn.c
index d55228aae..3e8c13de3 100644
--- a/src/lib/commands/turn.c
+++ b/src/lib/commands/turn.c
@@ -50,7 +50,7 @@ turn(void)
     struct telstr tgm;
     char *p;
     char buf[1024];
-    char msgbuf[MAXTELSIZE + 1]; /* message text */
+    char msgbuf[MAXTELSIZE + 1]; /* UTF-8 */
     char *msgfilepath;
 
     p = getstarg(player->argp[1], "on, off or motd? ", buf);
diff --git a/src/lib/gen/getstring.c b/src/lib/gen/getstring.c
index 0938cddfc..309183f71 100644
--- a/src/lib/gen/getstring.c
+++ b/src/lib/gen/getstring.c
@@ -44,19 +44,19 @@ getstring(char *prompt, char *buf)
 {
     *buf = '\0';
     if (prmptrd(prompt, buf, 1024) < 0)
-	return 0;
+	return NULL;
     return buf;
 }
 
 /*
- * Print sub-prompt PROMPT, receive a line of UTF8 input into BUF[1024].
+ * Print sub-prompt PROMPT, receive a line of UTF-8 input into BUF[1024].
  * Return BUF on success, else NULL.
  */
 char *
-ugetstring(char *prompt, char *buf /* buf is message text */)
+ugetstring(char *prompt, char *buf)
 {
     *buf = '\0';
     if (uprmptrd(prompt, buf, 1024) < 0)
-	return 0;
+	return NULL;
     return buf;
 }
diff --git a/src/lib/gen/parse.c b/src/lib/gen/parse.c
index d9551613d..b29cd4797 100644
--- a/src/lib/gen/parse.c
+++ b/src/lib/gen/parse.c
@@ -37,7 +37,7 @@
 
 /*
  * Parse user command in BUF.
- * BUF is user text.
+ * BUF is UTF-8.
  * Set ARG[0] to point to the command name.
  * Set ARG[1..N] to point to arguments, where N is the number of
  * arguments.  Set ARG[N+1..127] to NULL.
@@ -45,9 +45,8 @@
  * set *CONDP to the conditional argument if present, else NULL.
  * Command name and arguments are copied into SPACE[], whose size must
  * be at least strlen(BUF) + 1.
- * If *REDIR is not null, recognize the redirection syntax, and set
- * *REDIR to redirection string if present, else NULL.  The
- * redirection string is user text.
+ * If *REDIR is not null, recognize redirection syntax, and set *REDIR
+ * to UTF-8 redirection string if present, else NULL.
  * Return number of slots used in ARG[], or -1 on error.
  */
 int
diff --git a/src/lib/player/dispatch.c b/src/lib/player/dispatch.c
index 5d5454ba8..3b9fa2e09 100644
--- a/src/lib/player/dispatch.c
+++ b/src/lib/player/dispatch.c
@@ -48,10 +48,9 @@
 
 /*
  * Execute command named by player->argp[0].
- * BUF is the raw command line (user text).  It should have been
- * passed to parse() to set up player->argp.
- * If REDIR is not null, it's the command's redirection; it is user
- * text.
+ * BUF is the raw UTF-8 command line.  It should have been passed to
+ * parse() to set up player->argp.
+ * If REDIR is not null, it's the command's redirection, in UTF-8.
  * Return -1 if the command is not unique or doesn't exist, else 0.
  */
 int
diff --git a/src/lib/player/empdis.c b/src/lib/player/empdis.c
index 9ad05d6d4..9a516f91c 100644
--- a/src/lib/player/empdis.c
+++ b/src/lib/player/empdis.c
@@ -165,7 +165,7 @@ gamedown(void)
 {
     FILE *down_fp;
     struct telstr tgm;
-    char buf[MAXTELSIZE + 1];	/* message text */
+    char buf[MAXTELSIZE + 1];	/* UTF-8 */
 
     if (player->god)
 	return 0;
diff --git a/src/lib/player/player.c b/src/lib/player/player.c
index 88d600b6a..abf188784 100644
--- a/src/lib/player/player.c
+++ b/src/lib/player/player.c
@@ -158,7 +158,7 @@ int
 command(void)
 {
     unsigned int x;
-    char *redir;
+    char *redir;		/* UTF-8 */
     char scanspace[1024];
 
     if (getcommand(player->combuf) < 0)
@@ -306,18 +306,20 @@ execute(void)
     char buf[1024];
     int failed;
     char *p;
-    char *redir;
+    char *redir;		/* UTF-8 */
     char scanspace[1024];
 
     failed = 0;
-    redir = 0;
+    redir = NULL;
 
     p = getstarg(player->argp[1], "File? ", buf);
 
     if (p == NULL || *p == '\0')
 	return RET_SYN;
 
+    /* FIXME should use raw argument here, to support UTF-8 file names */
     prexec(player->argp[1]);
+
     while (!failed && status()) {
 	if (recvclient(buf, sizeof(buf)) < 0)
 	    break;
@@ -326,7 +328,7 @@ execute(void)
 	    failed = 1;
 	    continue;
 	}
-	if (redir == 0)
+	if (redir == NULL)
 	    pr("\nExecute : %s\n", buf);
 	if (dispatch(buf, redir) < 0)
 	    failed = 1;
@@ -334,7 +336,7 @@ execute(void)
     if (failed) {
 	while (recvclient(buf, sizeof(buf)) >= 0) ;
     }
-    if (redir == 0)
+    if (redir == NULL)
 	pr("Execute : %s\n", failed ? "aborted" : "terminated");
     return RET_OK;
 }
@@ -344,7 +346,7 @@ show_motd(void)
 {
     FILE *motd_fp;
     struct telstr tgm;
-    char buf[MAXTELSIZE + 1];	/* message text */
+    char buf[MAXTELSIZE + 1];	/* UTF-8 */
 
     if ((motd_fp = fopen(motdfil, "rb")) == NULL) {
     	if (errno == ENOENT)
diff --git a/src/lib/subs/getele.c b/src/lib/subs/getele.c
index 1fe4825a7..8e1a61922 100644
--- a/src/lib/subs/getele.c
+++ b/src/lib/subs/getele.c
@@ -40,17 +40,16 @@
 static int tilde_escape(char *s);
 
 /*
- * Read a telegram for RECIPIENT into BUF.
+ * Read a telegram for RECIPIENT into BUF, in UTF-8.
  * BUF must have space for MAXTELSIZE+1 characters.
  * Return telegram length, or -1 on error.
- * Note: telegrams are message text (see doc/unicode).
  */
 int
 getele(char *recipient, char *buf)
 {
     char *bp;
     size_t len;
-    char buffer[MAXTELSIZE + 2]; /* message text */
+    char buffer[MAXTELSIZE + 2]; /* UTF-8 */
     char left[16];
 
     pr("Enter telegram for %s\n", recipient);
diff --git a/src/lib/subs/pr.c b/src/lib/subs/pr.c
index 9c84549f7..8a4e72800 100644
--- a/src/lib/subs/pr.c
+++ b/src/lib/subs/pr.c
@@ -57,7 +57,12 @@
 
 static void outid(struct player *pl, int n);
 
-/*VARARGS*/
+/*
+ * Print to current player similar to printf().
+ * Use printf-style FORMAT with the optional arguments.
+ * Note: `to print' without further qualifications means sending
+ * C_DATA text.
+ */
 void
 pr(char *format, ...)
 {
@@ -68,8 +73,10 @@ pr(char *format, ...)
     (void)vsprintf(buf, format, ap);
     va_end(ap);
     if (player->flags & PF_UTF8)
+	/* normal text needs to be converted to user text */
 	upr_player(player, C_DATA, buf);
     else
+	/* normal text and user text are identical */
         pr_player(player, C_DATA, buf);
 }
 
@@ -90,11 +97,19 @@ uprnf(char *buf)
 	pr_player(player, C_DATA, buf);
 }
 
-/*VARARGS*/
+/*
+ * Send some text to P with id ID, line-buffered.
+ * Format text to send using printf-style FORMAT and optional
+ * arguments.  It is assumed to be already user text.  Plain ASCII and
+ * text received from the same player are fine, for anything else the
+ * caller has to deal with output filtering.
+ * If a partial line with different id is buffered, terminate it with
+ * a newline first.
+ */
 void
-pr_id(struct player *p, int id, s_char *format, ...)
+pr_id(struct player *p, int id, char *format, ...)
 {
-    s_char buf[4096];
+    char buf[4096];
     va_list ap;
 
     if (p->curid >= 0) {
@@ -107,11 +122,15 @@ pr_id(struct player *p, int id, s_char *format, ...)
     pr_player(p, id, buf);
 }
 
+/*
+ * Send C_FLASH text to PL.
+ * Format text to send using printf-style FORMAT and optional
+ * arguments.  It is assumed to be UTF-8.
+ */
 void
-pr_flash(struct player *pl, char *format
-	 /* format is message text */, ...)
+pr_flash(struct player *pl, char *format, ...)
 {
-    char buf[4096]; /* buf is message text */
+    char buf[4096];		/* UTF-8 */
     va_list ap;
 
     if (pl->state != PS_PLAYING)
@@ -125,10 +144,15 @@ pr_flash(struct player *pl, char *format
     io_output(pl->iop, IO_NOWAIT);
 }
 
+/*
+ * Send C_INFORM text to PL.
+ * Format text to send using printf-style FORMAT and optional
+ * arguments.  It is assumed to be plain ASCII.
+ */
 void
-pr_inform(struct player *pl, s_char *format, ...)
+pr_inform(struct player *pl, char *format, ...)
 {
-    s_char buf[4096];
+    char buf[4096];
     va_list ap;
 
     if (pl->state != PS_PLAYING)
@@ -140,10 +164,15 @@ pr_inform(struct player *pl, s_char *format, ...)
     io_output(pl->iop, IO_NOWAIT);
 }
 
+/*
+ * Send C_FLASH text to everyone.
+ * Format text to send using printf-style FORMAT and optional
+ * arguments.  It is assumed to be plain ASCII.
+ */
 void
-pr_wall(s_char *format, ...)
+pr_wall(char *format, ...)
 {
-    s_char buf[4096];
+    char buf[4096];		/* UTF-8 */
     struct player *p;
     va_list ap;
 
@@ -158,12 +187,18 @@ pr_wall(s_char *format, ...)
     }
 }
 
+/*
+ * Send ID text BUF to PL, line-buffered.
+ * BUF is user text.
+ * If a partial line with different id is buffered, terminate it with
+ * a newline first.
+ */
 void
-pr_player(struct player *pl, int id, s_char *buf)
+pr_player(struct player *pl, int id, char *buf)
 {
-    register s_char *p;
-    register s_char *bp;
-    register int len;
+    char *p;
+    char *bp;
+    int len;
 
     bp = buf;
     while (*bp != '\0') {
@@ -174,7 +209,7 @@ pr_player(struct player *pl, int id, s_char *buf)
 	if (pl->curid == -1)
 	    outid(pl, id);
 	p = strchr(bp, '\n');
-	if (p != 0) {
+	if (p != NULL) {
 	    len = (p - bp) + 1;
 	    if (pl->command && (pl->command->c_flags & C_MOD))
 		io_write(pl->iop, bp, len, IO_NOWAIT);
@@ -189,13 +224,17 @@ pr_player(struct player *pl, int id, s_char *buf)
     }
 }
 
+/*
+ * Send ID text BUF to PL, line-buffered.
+ * If a partial line with different id is buffered, terminate it with
+ * a newline first.
+ */
 void
-upr_player(struct player *pl, int id, char *buf
-                      /* buf is message text */)
+upr_player(struct player *pl, int id, char *buf)
 {
-    register char *bp; /* bp is message text */
-    register int standout = 0;
-    char printbuf[2]; /* bp is message text */
+    char *bp;
+    int standout = 0;
+    char printbuf[2];
     char ch;
 
     printbuf[0] = '\0';
@@ -258,7 +297,8 @@ pr_hilite(s_char *buf)
 }
 
 /*
- * output hex code + space
+ * Send id N to PL.
+ * This runs always at the beginning of a line.
  */
 static void
 outid(struct player *pl, int n)
@@ -278,58 +318,89 @@ outid(struct player *pl, int n)
     pl->curid = n;
 }
 
+/*
+ * Send redirection request REDIR to the current player.
+ * REDIR is UTF-8, but non-ASCII characters can occur only if the
+ * player sent them.  Therefore, it is also user text.
+ */
 void
-prredir(s_char *redir)
+prredir(char *redir)
 {
     pr_id(player, *redir == '>' ? C_REDIR : C_PIPE, "%s\n", redir);
 }
 
+/*
+ * Send script execute request FILE to the current player.
+ * REDIR is UTF-8, but non-ASCII characters can occur only if the
+ * player sent them.  Therefore, it is also user text.
+ */
 void
-prexec(s_char *file)
+prexec(char *file)
 {
     pr_id(player, C_EXECUTE, "%s\n", file);
 }
 
+/*
+ * Send a command prompt to the current player.
+ */
 void
 prprompt(int min, int btu)
 {
     pr_id(player, C_PROMPT, "%d %d\n", min, btu);
 }
 
+/*
+ * Prompt for a line of non-command input.
+ * Send C_FLUSH prompt PROMPT to the current player.
+ * Read a line of input into BUF[SIZE] and convert it to ASCII.
+ * Return number of bytes in BUF[], not counting the terminating 0,
+ * or -1 on error.
+ */
 int
-prmptrd(char *prompt, char *str, int size)
+prmptrd(char *prompt, char *buf, int size)
 {
     int r;
     char *cp;
 
     pr_id(player, C_FLUSH, "%s\n", prompt);
-    if ((r = recvclient(str, size)) < 0)
+    if ((r = recvclient(buf, size)) < 0)
 	return r;
     time(&player->curup);
-    if (*str == 0)
+    if (*buf == 0)
 	return 1;
     if (player->flags & PF_UTF8)
-	return copy_utf8_to_ascii_no_funny(str, str);
-    return copy_ascii_no_funny(str, str);
+	return copy_utf8_to_ascii_no_funny(buf, buf);
+    return copy_ascii_no_funny(buf, buf);
 }
 
+/*
+ * Prompt for a line of non-command, UTF-8 input.
+ * Send C_FLUSH prompt PROMPT to the current player.
+ * Read a line of input into BUF[SIZE], replacing funny characters by
+ * '?'.  The result is UTF-8.
+ * Return number of bytes in BUF[], not counting the terminating 0,
+ * or -1 on error.
+ */
 int
-uprmptrd(char *prompt, char *str /* str is message text */, int size)
+uprmptrd(char *prompt, char *buf, int size)
 {
     int r;
-    char *cp; /* cp is message text */
+    char *cp;
 
     pr_id(player, C_FLUSH, "%s\n", prompt);
-    if ((r = recvclient(str, size)) < 0)
+    if ((r = recvclient(buf, size)) < 0)
 	return r;
     time(&player->curup);
-    if (*str == 0)
+    if (*buf == 0)
 	return 1;
     if (player->flags & PF_UTF8)
-	return copy_utf8_no_funny(str, str);
-    return copy_ascii_no_funny(str, str);
+	return copy_utf8_no_funny(buf, buf);
+    return copy_ascii_no_funny(buf, buf);
 }
 
+/*
+ * Print the current time in ctime() format.
+ */
 void
 prdate(void)
 {
@@ -340,12 +411,14 @@ prdate(void)
 }
 
 /*
- * print x,y formatting as country
+ * Print coordinates X, Y for COUNTRY.
+ * FORMAT must be a printf-style format string that converts exactly
+ * two int values.
  */
 void
-prxy(s_char *format, coord x, coord y, natid country)
+prxy(char *format, coord x, coord y, natid country)
 {
-    s_char buf[255];
+    char buf[255];
     struct natstr *np;
 
     np = getnatp(country);
@@ -353,15 +426,23 @@ prxy(s_char *format, coord x, coord y, natid country)
     pr(buf);
 }
 
-/*VARARGS*/
+/*
+ * Print to country CN similar to printf().
+ * Use printf-style FORMAT with the optional arguments.
+ * Output is buffered until a newline arrives.
+ * If CN is the current player, print just like pr().
+ * Else print into a bulletin.
+ * Because printing like pr() requires normal text, and bulletins
+ * require user text, only plain ASCII is allowed.
+ */
 void
-PR(int cn, s_char *format, ...)
+PR(int cn, char *format, ...)
 {
     /* XXX should really do this on a per-nation basis */
-    static s_char longline[MAXNOC][512];
+    static char longline[MAXNOC][512];
     int newline;
     va_list ap;
-    s_char buf[1024];
+    char buf[1024];
 
     va_start(ap, format);
     (void)vsprintf(buf, format, ap);
@@ -377,6 +458,11 @@ PR(int cn, s_char *format, ...)
     }
 }
 
+/*
+ * Print the current time in ctime() format to country CN.
+ * If CN is the current player, print like prdate().
+ * Else print into a bulletin.
+ */
 void
 PRdate(natid cn)
 {
@@ -386,6 +472,9 @@ PRdate(natid cn)
     PR(cn, ctime(&now));
 }
 
+/*
+ * Sound the current player's bell.
+ */
 void
 pr_beep(void)
 {
@@ -395,10 +484,18 @@ pr_beep(void)
 	pr("\07");
 }
 
+/*
+ * Print to country CN similar to printf().
+ * Use printf-style FORMAT with the optional arguments.
+ * If CN is the current player, print just like pr().
+ * Else print into a bulletin.
+ * Because printing like pr() requires normal text, and bulletins
+ * require user text, only plain ASCII is allowed.
+ */
 void
-mpr(int cn, s_char *format, ...)
+mpr(int cn, char *format, ...)
 {
-    s_char buf[4096];
+    char buf[4096];
     va_list ap;
 
     va_start(ap, format);
diff --git a/src/lib/subs/wu.c b/src/lib/subs/wu.c
index 21377d365..b92e74c3b 100644
--- a/src/lib/subs/wu.c
+++ b/src/lib/subs/wu.c
@@ -80,8 +80,8 @@ telegram_is_new(natid to, struct telstr *tel)
 
 /*
  * Send a telegram from FROM to TO.
- * Format text to send under control of printf-style FORMAT using
- * optional arguments.  It is plain ASCII.
+ * Format text to send using printf-style FORMAT and optional
+ * arguments.  It is plain ASCII.
  * If running from the update, telegram type is TEL_UPDATE.
  * Else if FROM is a deity, type is TEL_BULLETIN.
  * Else it is TEL_NORM.
@@ -108,7 +108,7 @@ wu(natid from, natid to, char *format, ...)
 
 /*
  * Send a telegram from FROM to TO.
- * MESSAGE is the text to send, encoded as message text.
+ * MESSAGE is the text to send, in UTF-8.
  * TYPE is the telegram type.
  * Return 0 on success, -1 on error.
  */
-- 
2.43.0