Add a selftest that checks documentation invariants.

Several approaches were discussed (mail or irc) to verify the invariants of
the GDB help documentation : checking with apropos ., modifying add_cmd
to do the check and output a warning, implement maintenance check-doc.

A selftest was finally chosen as:
  * this can be run on demand, including by users if they want
    to check user defined commands.
  * it does not interact with the normal behaviour of apropos, define,
    python, ...
    (such as output warnings when a user defines a command help that
     does not respect the doc).
  * when the selftest runs, it checks the user defined and python
    defined commands currently defined.

gdb/ChangeLog
	* unittests/help-doc-selftests.c: New file.
	* Makefile.in: Add the new file.

3 files changed, 113 insertions, 0 deletions

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 03f70361903..9724858474d 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,10 @@
 2019-08-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
 
+	* unittests/help-doc-selftests.c: New file.
+	* Makefile.in: Add the new file.
+
+2019-08-07  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
+
 	* cli/cli-decode.h (print_doc_line): Add for_value_prefix argument.
 	* cli/cli-decode.c (print_doc_line): Likewise.  It now prints
 	the full first line, except when FOR_VALUE_PREFIX.  In this case,
diff --git a/gdb/Makefile.in b/gdb/Makefile.in
index 044627a0733..d5d095aae4d 100644
--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -414,6 +414,7 @@ SUBDIR_UNITTESTS_SRCS = \
 	unittests/environ-selftests.c \
 	unittests/format_pieces-selftests.c \
 	unittests/function-view-selftests.c \
+	unittests/help-doc-selftests.c \
 	unittests/lookup_name_info-selftests.c \
 	unittests/memory-map-selftests.c \
 	unittests/memrange-selftests.c \
diff --git a/gdb/unittests/help-doc-selftests.c b/gdb/unittests/help-doc-selftests.c
new file mode 100644
index 00000000000..89bc2e1f4e8
--- /dev/null
+++ b/gdb/unittests/help-doc-selftests.c
@@ -0,0 +1,107 @@
+/* Self tests for help doc for GDB, the GNU debugger.
+
+   Copyright (C) 2019 Free Software Foundation, Inc.
+
+   This file is part of GDB.
+
+   This program is free software; you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
+
+#include "defs.h"
+#include "cli/cli-cmds.h"
+#include "cli/cli-decode.h"
+#include "gdbsupport/selftest.h"
+
+namespace selftests {
+namespace help_doc_tests {
+
+static unsigned int nr_failed_invariants;
+
+/* Report a broken invariant and increments nr_failed_invariants.  */
+
+static void
+broken_doc_invariant (const char *prefix, const char *name, const char *msg)
+{
+  fprintf_filtered (gdb_stdout,
+		    "help doc broken invariant: command '%s%s' help doc %s\n",
+		    prefix, name, msg);
+  nr_failed_invariants++;
+}
+
+/* Recursively walk the commandlist structures, and check doc invariants:
+   - The first line of the doc must end with a '.'.
+   - the doc must not end with a new line.
+  If an invariant is not respected, produce a message and increment
+  nr_failed_invariants.
+  Note that we do not call SELF_CHECK in this function, as we want
+  all commands to be checked before making the test fail.  */
+
+static void
+check_doc (struct cmd_list_element *commandlist, const char *prefix)
+{
+  struct cmd_list_element *c;
+
+  /* Walk through the commands.  */
+  for (c = commandlist; c; c = c->next)
+    {
+      /* Checks the doc has a first line terminated with a '.'.  */
+      const char *p = c->doc;
+
+      /* Position p on the first LF, or on terminating null byte.  */
+      while (*p && *p != '\n')
+	p++;
+      if (p == c->doc)
+	broken_doc_invariant
+	  (prefix, c->name,
+	   "is missing the first line terminated with a '.' character");
+      else if (*(p-1) != '.')
+	broken_doc_invariant
+	  (prefix, c->name,
+	   "first line is not terminated with a '.' character");
+
+      /* Checks the doc is not terminated with a new line.  */
+      if (c->doc[strlen (c->doc) - 1] == '\n')
+	broken_doc_invariant
+	  (prefix, c->name,
+	   "has a superfluous trailing end of line");
+
+      /* Check if this command has subcommands and is not an
+	 abbreviation.  We skip checking subcommands of abbreviations
+	 in order to avoid duplicates in the output.  */
+      if (c->prefixlist != NULL && !c->abbrev_flag)
+	{
+	  /* Recursively call ourselves on the subcommand list,
+	     passing the right prefix in.  */
+	  check_doc (*c->prefixlist, c->prefixname);
+	}
+    }
+}
+
+static void
+help_doc_invariants_tests ()
+{
+  nr_failed_invariants = 0;
+  check_doc (cmdlist, "");
+  SELF_CHECK (nr_failed_invariants == 0);
+}
+
+} /* namespace help_doc_tests */
+} /* namespace selftests */
+
+void
+_initialize_help_doc_selftests ()
+{
+  selftests::register_test
+    ("help_doc_invariants",
+     selftests::help_doc_tests::help_doc_invariants_tests);
+}