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.
This is a big refactor of the clang driver's option handling to use
the Visibility flags introduced in https://reviews.llvm.org/D157149.
There are a few distinct parts, but they can't really be split into
separate commits and still be made to compile.
1. We split out some of the flags in ClangFlags to ClangVisibility.
Note that this does not include any subtractive flags.
2. We update the Flag definitions and OptIn/OptOut constructs in
Options.td by hand.
3. We introduce and use a script, update_options_td_flags, to ease
migration of flag definitions in Options.td, and we run that on
Options.td. I intend to remove this later, but I'm committing it so
that downstream forks can use the script to simplify merging.
4. We update calls to OptTable in the clang driver, cc1as, flang, and
clangd to use the visibility APIs instead of Include/Exclude flags.
5. We deprecate the Include/Exclude APIs and add a release note.
*if you are running into conflicts with this change:*
Note that https://reviews.llvm.org/D157150 may also be the culprit and
if so it should be handled first.
The script in `clang/utils/update_options_td_flags.py` can help. Take
the downstream side of all conflicts and then run the following:
```
% cd clang/include/clang/Driver
% ../../../utils/update_options_td_flags.py Options.td > Options.td.new
% mv Options.td.new Options.td
```
This will hopefully be sufficient, please take a look at the diff.
Differential Revision: https://reviews.llvm.org/D157151
Currently, FlangOptionsDocs.td doesn't specify `ExcludedFlags` which
means that in the generated documentation file we expose flags that:
* we don't necessarily won't to advertise to our users (e.g. hidden flags), or
* are not supported altogether (e.g. CL options).
This patch defines `ExcludeFlags` to fix that. The definition of
`ExcludeFlags` was copied from Clang so that LLVM frontends have
consistent documentation.
It might be a bit counter-intuitive that IncludeFlags alone is not
sufficient here. However, the current logic in ClangOptionDocEmitter.cpp
will parse IncludeFlags and print all options that contains one of the
included flags, as well as their aliases. So, for example, for -fopenmp
(which is a supported Flang option), one would also get /fopenmp (i.e.
CL mode equivalent for -fopenmp). By adding ExcludeFlags, we make sure
that such aliases are excluded.
I've also taken the liberty and moved FlangOptionsDocs.td. Originally it
was located in Flang's "flang/include" directory, but there shouldn't be
any implementation/documentation files there. Instead, I'm moving it to
the "flang/docs" directory.
Differential Revision: https://reviews.llvm.org/D130558
