[all-commits] [llvm/llvm-project] 09b80e: [clang][flang][driver] Correct program names in op...

[David Spickett via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: 09b80e6145a2e619fa8ff486a04cdc7d1534a81a
      https://github.com/llvm/llvm-project/commit/09b80e6145a2e619fa8ff486a04cdc7d1534a81a
  Author: David Spickett <david.spickett at linaro.org>
  Date:   2024-02-15 (Thu, 15 Feb 2024)

  Changed paths:
    M clang/include/clang/Driver/ClangOptionDocs.td
    M clang/include/clang/Driver/Options.td
    M clang/utils/TableGen/ClangOptionDocEmitter.cpp
    M flang/docs/FlangOptionsDocs.td

  Log Message:
  -----------
  [clang][flang][driver] Correct program names in option group descriptions (#81726)

Currently https://flang.llvm.org/docs/FlangCommandLineReference.html
refers to "Clang" in several of the group descriptions for example:
```
Compilation options

Flags controlling the behavior of Clang during compilation...
```

This is pretty confusing. I'm fixing this by making use of `Program`
from the existing GlobalDocumentation object to substitute in the
program name to these descriptions.

This `Program` has been changed to a proper noun given that it's easier
to lower case a string than capitalise one character (syntax wise). The
tablegen backend has been changed to lower it so that links in the
RST/HTML remain the same as they were before.

To make sure the file is valid when not generating docs, I'm checking a
#define and providing a default GlobalDocumentation if it's not defined.
(I looked for a way to check if a def exists, but tablegen doesn't seem
to have one)

This means that if the DocBrief are used outside of documentation,
they'll say "Clang", which is the same as it always was.

This change does not aim fix option descriptions that refer to clang.
Though we can use parts of this for that, there is only one driver
library so it needs a different approach.

This change also fixes the warning:
```
/home/buildbot/as-worker-4/publish-sphinx-docs/build/tools/flang/docs/Source/FlangCommandLineReference.rst:194: WARNING: unknown document: 'DiagnosticsReference'
```
Which is due to flang docs trying to link to clang docs. Now it will
just tell the reader to go to Clang's page, which is not ideal but it is
easy to find with Google at least.