Documenting the analyzer options

[DonatNagyE]

I noticed that the analyzer options (i.e. the content of AnalyzerOptions.def) are not documented anywhere within web documentation: neither in the modern RST-based documentation under clang/docs/analyzer, nor on the old HTML pages under clang/www/html. (Or at least, I couldn’t find anything relevant with git grep [Oo]ption.)

However, the file AnalyzerOptions.def contains some very minimal documentation for each option that it defines – I vaguely recall that clang prints these when some --help-like option is specified, but I don’t know the details. Unfortunately, this is an awkward place for this documentation, especially for those who use clang via a build system or CI job.

I think it would be important to document these options on an RST page within the “normal” documentation and I’m willing to put this together when I’ll have some time for it.

@Xazax-hun @NoQ @steakhal @Szelethus @ anybody else
What do you think about this?

• Do I understand the current situation correctly or did I happen to miss some accessible documentation?
• Would it be possible/useful to generate the RST docs automatically from the existing documentation fragments? If yes, then with what kind of workflow?
• What are the long-term plans about these options? Do you plan any large-scale change for the foreseeable future (that would invalidate this documentation)?

[steakhal]

@DonatNagyE

• Do I understand the current situation correctly or did I happen to miss some accessible documentation?

No, I think you are right. These options are not documented anywhere.

@DonatNagyE

• Would it be possible/useful to generate the RST docs automatically from the existing documentation fragments? If yes, then with what kind of workflow?

I think it would be useful to generate these from some declarative source. (Thinking of some Tablegen schema).

@DonatNagyE

• What are the long-term plans about these options? Do you plan any large-scale change for the foreseeable future (that would invalidate this documentation)?

I’m not aware of long term plans for changing/eradicating any of these options.

FYI at the time I was at Ericsson, I was prototyping with a Tablegen declarative approach that would not only document the options, but allow xrefing them even from checker documentations etc.
I highly recommend you to check out my RFC where I described what I had exactly in mind. I still have the 3 years old code on my branch here. It’s probably not that difficult to rebase. Use it as you wish.