Hello,
This is the first patch-set to better document clang diagnostics.
I have added two fields into the Diagnostic (.td) class: Brief and Explanation; and modified the subsequent generation (and exploitation) of the table
I have added two getters to DiagnosticIDs to get the “BriefExplanation” and “FullExplanation”
There is also a few corrections of comments that were (it seems) out of sync
Note: there is one (little) patch for LLVM, because the TableGen backend is in llvm repository… and the two patches are intrisically tied (obviously)
Note 2: is this normally tested or do we assume that is compilation a test in itself ?
Compilation, plus any tests for the feature that the TableGen changes support, are enough.
Unless we want the same Brief / Explanation for Groups too, this normally implement the “libclang” part, so next are the HTML pages generation and the Help menu modification.
I don’t think we need to worry about this just yet.
For those tasks, the distinction of where the diagnostic comes from probably does not makes sense for the user, so I would expect to have to group the warnings using the categories and subgroups rather than AST/Sema/Parse.
Yes. More categorization of the existing diagnostics would be useful.
I suppose that we’ll want to expose both warnings and extension warnings here.
Yes.
There is one catch though: the individual warnings are not named. I was wondering if I should create a name (#ENUM in the macro ? The internal ID ?) or if the Brief would be enough and I’d just list all the briefs/explanations underneath the subgroup they belong to.
Well, the warnings do have the names they’re given in the .td files, e.g.,
def err_array_init_not_init_list : Error<
"array initializer must be an initializer "
“list%select{| or string literal}0”>;
We could take the diagnostic name without the err_/ext_/warn_ prefix, so the name of this diagnostic would be “array_init_not_init_list”. TableGen could expose this as the diagnostic name.
With regard to the HTML generation: I was thinking about using a Python script and invoke it as part of the build step. This would require, I guess, that I update the Python Bindings (if any ?) to extract the information from libclang. I’d appreciate pointers to the documentation (if any).
Well, that’s certainly one approach. You’d need to extend libclang to provide diagnostic documentation information, and update the Python bindings for libclang. I guess the benefit is that it’s easier to emit HTML from a Python script than from C++.
Personally, I think you should start simpler: add a flag that teaches the diagnostic printer to emit the name of the diagnostic as part of the brackets, e.g.,
warning: semicolon before method body is ignored [-Wsemicolon-before-method-body, semicolon_before_method_body]
and then add some kind of --help option that looks up the documentation for a diagnostic based on that name, e.g.,
clang --help semicolon_before_method_body
With this working, you’ll be able to write regression tests that ensure that we’re getting the right documentation for the right names. And users could use this feature to get more information about a particular diagnostic. That entire system could be in place before you start worrying about the formatting of HTML itself, so other people could help fill in content.
