[cfe-dev] clang/Driver/Options.td, docs/UsersManual.rst and docs/ClangCommandLineReference.rst

[Robinson, Paul via cfe-dev]

> -----Original Message-----
> From: cfe-dev <cfe-dev-bounces at lists.llvm.org> On Behalf Of Fang-ruì Sòng
> via cfe-dev
> Sent: Monday, September 28, 2020 4:10 PM
> To: cfe-dev <cfe-dev at lists.llvm.org>
> Subject: [cfe-dev] clang/Driver/Options.td, docs/UsersManual.rst and
> docs/ClangCommandLineReference.rst
> 
> As I know the documentation of command line options are in two places:
> 
> * include/clang/Driver/Options.td (DocBreif and HelpText are used to
> generate docs/ClangCommandLineReference.rst
> (https://urldefense.com/v3/__https://clang.llvm.org/docs/ClangCommandLineR
> eference.html__;!!JmoZiZGBv3RvKRSx!r44VGtJUru9yhX18MzZNOG094Igpn6BT2PfE-
> 7Uec7ox4dLCcn_O0n29agoom8_0zQ$  ))
> * docs/UsersManual.rst : This is manually edited. It is more like a
> book. My understanding is that the manual only contains frequently
> used options.
> 
> docs/ClangCommandLineReference.rst actually lacks lots of stuff from
> docs/UsersManual.rst (I have seen people complaining that more than a
> half of options on ClangCommandLineReference have no documentation). I
> wonder whether there is a better way organizing the documentation. For
> example, if some description are written in docs/UsersManual.rst, it'd
> be nice for ClangCommandLineReference to inherit those.
> 
> (The documentation of attributes is in a separate file:
> include/clang/Basic/AttrDocs.td
> (https://urldefense.com/v3/__https://clang.llvm.org/docs/AttributeReferenc
> e.html__;!!JmoZiZGBv3RvKRSx!r44VGtJUru9yhX18MzZNOG094Igpn6BT2PfE-
> 7Uec7ox4dLCcn_O0n29agrkFPXGmA$ ) Does Options.td
> need to learn from it?)

I think moving the option documentation toward something modeled
on the attribute documentation is an excellent idea.  The way 
attributes are done, the attribute definition has to explicitly 
state whether more detailed documentation exists.  Having that 
"no documentation" statement in the source is the right level of 
"you should do this" motivation.

There could be a way to say that the reference manual documentation
is just the online help text, I suppose.

Maybe the "hidden" options should be documented in a separate 
section of the reference manual?  As they are "hidden" and not 
meant to be used normally.

--paulr