elog: document style guidelines for error message functions

Add brief style guidelines to the header comments of errmsg(),
errdetail(), errhint(), errcontext() and elog.

The styles are described in:

* https://www.postgresql.org/docs/current/error-style-guide.html
* https://www.postgresql.org/docs/devel/error-message-reporting.html

Author: Chao Li <lic@highgo.com>

Author: Chao Li (Evan)

src/backend/utils/error/elog.c

@@ -1087,6 +1087,9 @@ errcode_for_socket_access(void)
  * In addition to the usual %-escapes recognized by printf, "%m" in
  * fmt is replaced by the error message for the caller's value of errno.
  *
+ * Style guidelines: do not capitalize the first letter, and do not end
+ * the message with a period or other punctuation.
+ *
  * Note: no newline is needed at the end of the fmt string, since
  * ereport will provide one for the output methods that need it.
  */
@@ -1390,6 +1393,11 @@ errmsg_plural(const char *fmt_singular, const char *fmt_plural,
 
 /*
  * errdetail --- add a detail error message text to the current error
+ *
+ * Style guidelines: use complete sentences; capitalize the first word
+ * of each sentence, and end each with a period; put two spaces after
+ * a period if another sentence follows (for English text; may be
+ * inappropriate in other languages).
  */
 int
 errdetail(const char *fmt, ...)
@@ -1504,6 +1512,11 @@ errdetail_plural(const char *fmt_singular, const char *fmt_plural,
 
 /*
  * errhint --- add a hint error message text to the current error
+ *
+ * Style guidelines: use complete sentences; capitalize the first word
+ * of each sentence, and end each with a period; put two spaces after
+ * a period if another sentence follows (for English text; may be
+ * inappropriate in other languages).
  */
 int
 errhint(const char *fmt, ...)

src/include/utils/elog.h

@@ -210,6 +210,9 @@ extern int	errhint_plural(const char *fmt_singular, const char *fmt_plural,
  * is not usually the correct domain for translating the context message.
  * set_errcontext_domain() first sets the domain to be used, and
  * errcontext_msg() passes the actual message.
+ *
+ * Style guidelines: do not capitalize the first letter, do not end the string
+ * with a period, and avoid complete sentences.
  */
 #define errcontext	set_errcontext_domain(TEXTDOMAIN),	errcontext_msg
 
@@ -237,6 +240,11 @@ extern int	getinternalerrposition(void);
 /*----------
  * Old-style error reporting API: to be used in this way:
  *		elog(ERROR, "portal \"%s\" not found", stmt->portalname);
+ *
+ * elog() is intended for internal errors and low-level debug logging.
+ * It always uses a default SQLSTATE, and the message is not translated.
+ * Messages that may be of interest to end users should use ereport()
+ * instead.
  *----------
  */
 #define elog(elevel, ...)  \