diagnostics: UX: add doc URLs for attributes (v2)

This is v2 of the patch; v1 was here:
  https://gcc.gnu.org/pipermail/gcc-patches/2024-June/655541.html

Changed in v2:
* added a new TARGET_DOCUMENTATION_NAME hook for figuring out which
  documentation URL to use when there are multiple per-target docs,
  such as for __attribute__((interrupt)); implemented this for all
  targets that have target-specific attributes
* moved attribute_urlifier and its support code to a new
  gcc-attribute-urlifier.cc since it needs to use targetm for the
  above; gcc-urlifier.o is used by the driver.
* fixed extend.texi so that some attributes that failed to appear in
  attr-urls.def now do so (affected nvptx "kernel" and "shared" attrs)
* regenerated attr-urls.def for the above fix, and bringing in
  attributes added since v1 of the patch

In r14-5118-gc5db4d8ba5f3de I added a mechanism to automatically add
documentation URLs to quoted strings in diagnostics.
In r14-6920-g9e49746da303b8 I added a mechanism to generate URLs for
mentions of command-line options in quoted strings in diagnostics.

This patch does a similar thing for attributes.  It adds a new Python 3
script to scrape the generated HTML looking for documentation of
attributes, and uses this to (re)generate a new gcc/attr-urls.def file.

Running "make regenerate-attr-urls" after rebuilding the HTML docs will
regenerate gcc/attr-urls.def in the source directory.

The patch uses this to optionally add doc URLs for attributes in any
diagnostic emitted during the lifetime of a auto_urlify_attributes
instance, and adds such instances everywhere that a diagnostic refers
to a diagnostic within quotes (based on grepping the source tree
for references to attributes in strings and in code).

For example, given:

$ ./xgcc -B. -S ../../src/gcc/testsuite/gcc.dg/attr-access-2.c
../../src/gcc/testsuite/gcc.dg/attr-access-2.c:14:16: warning:
attribute ‘access(read_write, 2, 3)’ positional argument 2 conflicts
with previous designation by argument 1 [-Wattributes]

with this patch the quoted text `access(read_write, 2, 3)'
automatically gains the URL for our docs for "access":
https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-access-function-attribute
in a sufficiently modern terminal.

Like r14-6920-g9e49746da303b8 this avoids the Makefile target
depending on the generated HTML, since a missing URL is a minor
problem, whereas requiring all users to build HTML docs seems more
involved.  Doing so also avoids Python 3 as a build requirement for
everyone, but instead just for developers addding attributes.
Like the options, we could add a CI test for this.

The patch gathers both general and target-specific attributes.
For example, the function attribute "interrupt" has 19 URLs within our
docs: one common, and 18 target-specific ones.
The patch adds a new target hook used when selecting the most
appropriate one.

Signed-off-by: David Malcolm <dmalcolm@redhat.com>

gcc/ChangeLog:
	* Makefile.in (OBJS): Add -attribute-urlifier.o.
	(ATTR_URLS_HTML_DEPS): New.
	(regenerate-attr-urls): New.
	(regenerate-attr-urls-unit-test): New.
	* attr-urls.def: New file.
	* attribs.cc: Include "gcc-urlifier.h".
	(decl_attributes): Use auto_urlify_attributes.
	* config/aarch64/aarch64.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/arc/arc.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/arm/arm.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/bfin/bfin.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/bpf/bpf.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/epiphany/epiphany.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/gcn/gcn.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/h8300/h8300.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/i386/i386.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/ia64/ia64.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/m32c/m32c.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/m32r/m32r.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/m68k/m68k.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/mcore/mcore.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/microblaze/microblaze.cc (TARGET_DOCUMENTATION_NAME):
	New.
	* config/mips/mips.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/msp430/msp430.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/nds32/nds32.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/nvptx/nvptx.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/riscv/riscv.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/rl78/rl78.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/rs6000/rs6000.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/rx/rx.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/s390/s390.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/sh/sh.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/stormy16/stormy16.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/v850/v850.cc (TARGET_DOCUMENTATION_NAME): New.
	* config/visium/visium.cc (TARGET_DOCUMENTATION_NAME): New.

gcc/analyzer/ChangeLog:
	* region-model.cc: Include "gcc-urlifier.h".
	(reason_attr_access::emit): Use auto_urlify_attributes.
	* sm-taint.cc: Include "gcc-urlifier.h".
	(tainted_access_attrib_size::emit): Use auto_urlify_attributes.

gcc/c-family/ChangeLog:
	* c-attribs.cc: Include "gcc-urlifier.h".
	(positional_argument): Use auto_urlify_attributes.
	* c-common.cc: Include "gcc-urlifier.h".
	(parse_optimize_options): Use auto_urlify_attributes with
	OPT_Wattributes.
	(attribute_fallthrough_p): Use auto_urlify_attributes.
	* c-warn.cc: Include "gcc-urlifier.h".
	(diagnose_mismatched_attributes): Use auto_urlify_attributes.

gcc/c/ChangeLog:
	* c-decl.cc: Include "gcc-urlifier.h".
	(start_decl): Use auto_urlify_attributes with OPT_Wattributes.
	(start_function): Likewise.
	* c-parser.cc: Include "gcc-urlifier.h".
	(c_parser_statement_after_labels): Use auto_urlify_attributes with
	OPT_Wattributes.
	* c-typeck.cc: Include "gcc-urlifier.h".
	(maybe_warn_nodiscard): Use auto_urlify_attributes with
	OPT_Wunused_result.

gcc/cp/ChangeLog:
	* cp-gimplify.cc: Include "gcc-urlifier.h".
	(process_stmt_hotness_attribute): Use auto_urlify_attributes with
	OPT_Wattributes.
	* cvt.cc: Include "gcc-urlifier.h".
	(maybe_warn_nodiscard): Use auto_urlify_attributes with
	OPT_Wunused_result.
	* decl.cc: Include "gcc-urlifier.h".
	(start_decl): Use auto_urlify_attributes.
	(start_preparsed_function): Likewise.

gcc/ChangeLog:
	* diagnostic.cc (diagnostic_context::override_urlifier): New.
	* diagnostic.h (diagnostic_context::override_urlifier): New decl.
	* doc/extend.texi (Nvidia PTX Function Attributes): Update
	@cindex to specify that "kernel" is a function attribute and
	"shared" is a variable attribute, so that these entries are
	recognized by the regex in regenerate-attr-urls.py.
	* doc/tm.texi: Regenerate.
	* doc/tm.texi.in (TARGET_DOCUMENTATION_NAME): New.
	* gcc-attribute-urlifier.cc: New file.
	* gcc-urlifier.cc: Include diagnostic.h.
	(gcc_urlifier::make_doc): Convert to...
	(make_doc_url): ...this.
	(auto_override_urlifier::auto_override_urlifier): New.
	(auto_override_urlifier::~auto_override_urlifier): New.
	(selftest::gcc_urlifier_cc_tests): Split out body into...
	(selftest::test_gcc_urlifier): ...this.
	* gcc-urlifier.h: Include "pretty-print-urlifier.h" and "label-text.h".
	(make_doc_url): New decl.
	(class auto_override_urlifier): New.
	(class attribute_urlifier): New.
	(class auto_urlify_attributes): New.
	* gimple-ssa-warn-access.cc: Include "gcc-urlifier.h".
	(pass_waccess::execute): Use auto_urlify_attributes.
	* gimplify.cc: Include "gcc-urlifier.h".
	(expand_FALLTHROUGH): Use auto_urlify_attributes.
	* internal-fn.cc: Define INCLUDE_MEMORY and include
	"gcc-urlifier.h.
	(expand_FALLTHROUGH): Use auto_urlify_attributes.
	* ipa-pure-const.cc: Include "gcc-urlifier.h.
	(suggest_attribute): Use auto_urlify_attributes.
	* ipa-strub.cc: Include "gcc-urlifier.h.
	(can_strub_p): Use auto_urlify_attributes.
	* regenerate-attr-urls.py: New file.
	* selftest-run-tests.cc (selftest::run_tests): Call
	gcc_attribute_urlifier_cc_tests.
	* selftest.h (selftest::gcc_attribute_urlifier_cc_tests): New
	decl.
	* target.def (documentation_name): New DEFHOOKPOD.
	* tree-cfg.cc: Include "gcc-urlifier.h.
	(do_warn_unused_result): Use auto_urlify_attributes.
	* tree-ssa-uninit.cc: Include "gcc-urlifier.h.
	(maybe_warn_read_write_only): Use auto_urlify_attributes.
	(maybe_warn_pass_by_reference): Likewise.

Signed-off-by: David Malcolm <dmalcolm@redhat.com>

3 files changed, 18 insertions, 5 deletions

diff --git a/gcc/c-family/c-attribs.cc b/gcc/c-family/c-attribs.cc
index 5b64805..eb76a9e 100644
--- a/gcc/c-family/c-attribs.cc
+++ b/gcc/c-family/c-attribs.cc
@@ -48,6 +48,7 @@ along with GCC; see the file COPYING3.  If not see
 #include "gimplify.h"
 #include "tree-pretty-print.h"
 #include "gcc-rich-location.h"
+#include "gcc-urlifier.h"
 
 static tree handle_packed_attribute (tree *, tree, tree, int, bool *);
 static tree handle_nocommon_attribute (tree *, tree, tree, int, bool *);
@@ -737,6 +738,8 @@ positional_argument (const_tree fn, const_tree atname, tree &pos,
 		     tree_code code, int argno /* = 0 */,
 		     int flags /* = posargflags () */)
 {
+  auto_urlify_attributes sentinel;
+
   const_tree fndecl = TYPE_P (fn) ? NULL_TREE : fn;
   const_tree fntype = TYPE_P (fn) ? fn : TREE_TYPE (fn);
   if (pos && TREE_CODE (pos) != IDENTIFIER_NODE
diff --git a/gcc/c-family/c-common.cc b/gcc/c-family/c-common.cc
index 0489523..ccf5f41 100644
--- a/gcc/c-family/c-common.cc
+++ b/gcc/c-family/c-common.cc
@@ -55,6 +55,7 @@ along with GCC; see the file COPYING3.  If not see
 #include "vec-perm-indices.h"
 #include "tree-pretty-print-markup.h"
 #include "gcc-rich-location.h"
+#include "gcc-urlifier.h"
 
 cpp_reader *parse_in;		/* Declared in c-pragma.h.  */
 
@@ -6105,8 +6106,11 @@ parse_optimize_options (tree args, bool attr_p)
 		{
 		  ret = false;
 		  if (attr_p)
-		    warning (OPT_Wattributes,
-			     "bad option %qs to attribute %<optimize%>", p);
+		    {
+		      auto_urlify_attributes sentinel;
+		      warning (OPT_Wattributes,
+			       "bad option %qs to attribute %<optimize%>", p);
+		    }
 		  else
 		    warning (OPT_Wpragmas,
 			     "bad option %qs to pragma %<optimize%>", p);
@@ -6155,9 +6159,12 @@ parse_optimize_options (tree args, bool attr_p)
 	{
 	  ret = false;
 	  if (attr_p)
-	    warning (OPT_Wattributes,
-		     "bad option %qs to attribute %<optimize%>",
-		     decoded_options[i].orig_option_with_args_text);
+	    {
+	      auto_urlify_attributes sentinel;
+	      warning (OPT_Wattributes,
+		       "bad option %qs to attribute %<optimize%>",
+		       decoded_options[i].orig_option_with_args_text);
+	    }
 	  else
 	    warning (OPT_Wpragmas,
 		     "bad option %qs to pragma %<optimize%>",
@@ -6205,6 +6212,7 @@ attribute_fallthrough_p (tree attr)
   tree t = lookup_attribute ("", "fallthrough", attr);
   if (t == NULL_TREE)
     return false;
+  auto_urlify_attributes sentinel;
   /* It is no longer true that "this attribute shall appear at most once in
      each attribute-list", but we still give a warning.  */
   if (lookup_attribute ("", "fallthrough", TREE_CHAIN (t)))
diff --git a/gcc/c-family/c-warn.cc b/gcc/c-family/c-warn.cc
index 7433bc0..140d97a 100644
--- a/gcc/c-family/c-warn.cc
+++ b/gcc/c-family/c-warn.cc
@@ -40,6 +40,7 @@ along with GCC; see the file COPYING3.  If not see
 #include "stor-layout.h"
 #include "tree-pretty-print.h"
 #include "langhooks.h"
+#include "gcc-urlifier.h"
 
 /* Print a warning if a constant expression had overflow in folding.
    Invoke this function on every expression that the language
@@ -2676,6 +2677,7 @@ warn_duplicated_cond_add_or_warn (location_t loc, tree cond, vec<tree> **chain)
 bool
 diagnose_mismatched_attributes (tree olddecl, tree newdecl)
 {
+  auto_urlify_attributes sentinel;
   bool warned = false;
 
   tree a1 = lookup_attribute ("optimize", DECL_ATTRIBUTES (olddecl));