[PATCH] D147141: [clang][documentation][enhancement]Documented Optimization Flags

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

We already have documentation for these: https://clang.llvm.org/docs/CommandGuide/clang.html#code-generation-options

I think there's sufficient confusion in this space that we should fix *something*. We have at least three places where we list a lot of command line options and details about them:

https://clang.llvm.org/docs/ClangCommandLineReference.html
https://clang.llvm.org/docs/UsersManual.html#command-line-options
https://clang.llvm.org/docs/CommandGuide/clang.html

I think that if we did anything in this area, it would be to figure out how these documents relate to one another and move information around to the correct places (probably while adding explicit links between the documents). I believe the way these are intended to work is that the command guide is basically the `man` page for clang, so it should follow the usual manpage style and content amounts, while the command line reference is the table-generated documentation detailing every command line option Clang supports, and the User's Manual is less about command line and more about implementation-defined behavior in general. So I think what I'd prefer is:

- copy the documentation from the user's manual into Options.td so that the full command line reference file will display the information,
- replace the documentation about the command line in the user's manual with a link to the command guide ("For information about command line options, please see <link>.", effectively),
- ensure that the documentation for command line options listed explicitly in the command guide also exists in Options.td for the full command line reference,
- add a link to the full command line reference from the command guide ("For a list of all command line options supported by Clang, please see <link>.", effectively),
- add a new section about documentation to the internals manual to describe this policy of where command line docs should live.

However, @ipriyanshi1708, don't feel like you're obligated to work on any of this unless you feel like it. It's a fair amount of effort that would be split out over quite a few patches that may need some tweaks to correct documentation details that are unclear or no longer accurate.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D147141/new/

https://reviews.llvm.org/D147141