From patchwork Sat Aug 3 13:39:21 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philippe Waroquiers X-Patchwork-Id: 33948 Received: (qmail 116215 invoked by alias); 3 Aug 2019 13:39:35 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 116135 invoked by uid 89); 3 Aug 2019 13:39:34 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-20.0 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_SHORT, RCVD_IN_DNSWL_LOW, SPF_PASS autolearn=ham version=3.3.1 spammy=abbreviation X-HELO: mailsec116.isp.belgacom.be Received: from mailsec116.isp.belgacom.be (HELO mailsec116.isp.belgacom.be) (195.238.20.112) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Sat, 03 Aug 2019 13:39:32 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=skynet.be; i=@skynet.be; q=dns/txt; s=securemail; t=1564839572; x=1596375572; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=mOoA2zTr87M8qwcXcpybGh28MzhLIKGX0DlEUau3IVU=; b=mLFTt3vQ6ZuIN6q5fCQk6wYgjwPFF5D2FJfK9ZijvGTvSS7X9gqzwvS9 Ra3oOHPCCWxcPqCr73xBoSRGij0PZg==; Received: from 96.218-128-109.adsl-dyn.isp.belgacom.be (HELO md.home) ([109.128.218.96]) by relay.skynet.be with ESMTP/TLS/DHE-RSA-AES128-GCM-SHA256; 03 Aug 2019 15:39:28 +0200 From: Philippe Waroquiers To: gdb-patches@sourceware.org Cc: Philippe Waroquiers Subject: [RFAv2 2/2] Add a selftest that checks documentation invariants. Date: Sat, 3 Aug 2019 15:39:21 +0200 Message-Id: <20190803133921.20154-3-philippe.waroquiers@skynet.be> In-Reply-To: <20190803133921.20154-1-philippe.waroquiers@skynet.be> References: <20190803133921.20154-1-philippe.waroquiers@skynet.be> MIME-Version: 1.0 X-IsSubscribed: yes 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. --- gdb/Makefile.in | 1 + gdb/unittests/help-doc-selftests.c | 106 +++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 gdb/unittests/help-doc-selftests.c diff --git a/gdb/Makefile.in b/gdb/Makefile.in index 01ff0c0c20..b689769e13 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 0000000000..8335ad581e --- /dev/null +++ b/gdb/unittests/help-doc-selftests.c @@ -0,0 +1,106 @@ +/* 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 . */ + +#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; + + 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); +}