From: Ralph Corderoy <ralph@inputplus.co.uk>
Date: Sat, 22 Apr 2017 23:29:02 +0000 (+0100)
Subject: Add first-line comment describing C source's purpose.
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/ddf5b0259b7246c0d3207ceb22ea72379ae64e89?hp=010cd7a621c0bc807c083a462183d7554063559e

Add first-line comment describing C source's purpose.

I had a stab at them after a bit of a skim;  they're better than
nothing.
---

diff --git a/h/netsec.h b/h/netsec.h
index e22b39e3..c0729908 100644
--- a/h/netsec.h
+++ b/h/netsec.h
@@ -1,4 +1,4 @@
-/* Network security library routines for nmh.
+/* netsec.h -- network-security library routines.
  *
  * These are a common set of routines to handle network security for
  * things like SASL and OpenSSL.
diff --git a/h/oauth.h b/h/oauth.h
index d5098730..605008a1 100644
--- a/h/oauth.h
+++ b/h/oauth.h
@@ -1,12 +1,12 @@
-/* Implementation of OAuth 2.0 [1] for XOAUTH2 in SMTP [2] and POP3 [3].
+/* oauth.h -- OAuth 2.0 implementation for XOAUTH2 in SMTP and POP3.
  *
  * Google defined XOAUTH2 for SMTP, and that's what we use here.  If other
  * providers implement XOAUTH2 or some similar OAuth-based SMTP authentication
  * protocol, it should be simple to extend this.
  *
- * [1] https://tools.ietf.org/html/rfc6749
- * [2] https://developers.google.com/gmail/xoauth2_protocol
- * [3] http://googleappsdeveloper.blogspot.com/2014/10/updates-on-authentication-for-gmail.html
+ * OAuth  https://tools.ietf.org/html/rfc6749
+ * SMTP   https://developers.google.com/gmail/xoauth2_protocol
+ * POP3   http://googleappsdeveloper.blogspot.com/2014/10/updates-on-authentication-for-gmail.html
  *
  * Presumably [2] should document POP3 and that is an over-sight.  As it stands,
  * that blog post is the closest we have to documentation.
diff --git a/sbr/credentials.c b/sbr/credentials.c
index 3aba7d80..b34b9673 100644
--- a/sbr/credentials.c
+++ b/sbr/credentials.c
@@ -1,4 +1,6 @@
-/* This code is Copyright (c) 2013, by the authors of nmh.  See the
+/* credentials.c -- wrap configurable access to .netrc or similar files.
+ *
+ * This code is Copyright (c) 2013, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
  * complete copyright information.
  */
diff --git a/sbr/encode_rfc2047.c b/sbr/encode_rfc2047.c
index 41fe7865..bc5fc1be 100644
--- a/sbr/encode_rfc2047.c
+++ b/sbr/encode_rfc2047.c
@@ -1,4 +1,4 @@
-/* Routines to encode message headers using RFC 2047-encoding.
+/* encode_rfc2047.c -- encode message headers using RFC 2047 encoding.
  *
  * This code is Copyright (c) 2002, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
diff --git a/sbr/getpass.c b/sbr/getpass.c
index a6a1f13c..4b24af3c 100644
--- a/sbr/getpass.c
+++ b/sbr/getpass.c
@@ -1,4 +1,6 @@
-/* Portions of this code are Copyright (c) 1988, 1993
+/* getpass.c -- read a password without echo.
+ *
+ * Portions of this code are Copyright (c) 1988, 1993
  *	The Regents of the University of California.  All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
diff --git a/sbr/norm_charmap.c b/sbr/norm_charmap.c
index d9580bce..b10cde34 100644
--- a/sbr/norm_charmap.c
+++ b/sbr/norm_charmap.c
@@ -1,4 +1,6 @@
-/* The Single Unix Specification function nl_langinfo(CODESET)
+/* norm_charmap.c -- map locale's encoding to MIME charset.
+ *
+ * The Single Unix Specification function nl_langinfo(CODESET)
  * returns the name of the encoding used by the currently selected
  * locale:
  *
diff --git a/sbr/oauth.c b/sbr/oauth.c
index f286d165..3becfdef 100755
--- a/sbr/oauth.c
+++ b/sbr/oauth.c
@@ -1,4 +1,6 @@
-/* This code is Copyright (c) 2014, by the authors of nmh.  See the
+/* oauth.c -- OAuth 2.0 implementation for XOAUTH2 in SMTP and POP3.
+ *
+ * This code is Copyright (c) 2014, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
  * complete copyright information.
  */
diff --git a/sbr/oauth_prof.c b/sbr/oauth_prof.c
index c51cf0a4..3dc50732 100644
--- a/sbr/oauth_prof.c
+++ b/sbr/oauth_prof.c
@@ -1,4 +1,6 @@
-/* This code is Copyright (c) 2014, by the authors of nmh.  See the
+/* oauth_prof.c -- OAuth 2.0 implementation for XOAUTH2 in SMTP and POP3.
+ *
+ * This code is Copyright (c) 2014, by the authors of nmh.  See the
  * COPYRIGHT file in the root directory of the nmh distribution for
  * complete copyright information.
  */
diff --git a/sbr/ruserpass.c b/sbr/ruserpass.c
index 6b1d1a13..1e43571e 100644
--- a/sbr/ruserpass.c
+++ b/sbr/ruserpass.c
@@ -1,4 +1,6 @@
-/* Portions of this code are
+/* ruserpass.c -- parse .netrc-format file.
+ *
+ * Portions of this code are
  * Copyright (c) 1985 Regents of the University of California.
  * All rights reserved.
  *