[cfe-commits] Improving Diagnostics Documentation: Part 1

[Douglas Gregor]

On Apr 15, 2011, at 12:29 PM, Matthieu Monrocq wrote:

> Hello,
> 
> Here are two small patches to begin on the road toward improving diagnostics documentation.
> 
> The goal here is to provide a way for the user, either through libclang, the clang binary, or the website, to get some documentation for a particular diagnostic that has been raised during the compilation.
> 
> Those two patches implement the first drop:
> > Extension of the Diagnotic object with 3 fields: Name (simply the enum under a char const* form), Brief (a summary of the issue), Explanation (an extensive explanation of the issue, possibly with various illustrations and their corrections, in case a single fix-it is not suitable)

Okay.

> > Provide an option in the Driver to activate/deactive printing the name of the Diagnostic in the error output (active by default), print the Diagnostic name in the error output (for all but notes), provide a test case for the option (active/inactive)

We should turn this off by default (which I've done); we'll turn it on once there's enough content available to make it worthwhile for end users.

> > Implement an Index to get back the Diagnostic ID from a name (log2 N complexity as it's a sorted array, N ~ 2173 in my revision)
> 
> *Important*: I do not use the Makefile system, and as such was not able to check whether this still built. It's kind of a special patch since we generate a new file with tblgen...
> 
> *Important*: As any modification of the tblgen backend, the two patches (against clang and llvm) are interdependent.
> 
> Note: I first tried dropping the "prefix" of the enum (warn_, fatal_, etc...) however this created conflicts between different diagnostics. I am not strongly attached to either dropping it or not, but since dropping it involved renaming some enums, I preferred using the full name for now.

I think that, eventually, we'll want to consider diagnostics to be the same if they differ only by prefix, since we have a number of places where we have (conceptually) the same diagnostic with two forms: an err_ form where it has to be an error, and an ext_form where it doesn't. That said, we don't need to solve this problem now.

Thanks! Committed as LLVM r129613 and Clang r129614, respectively.

	- Doug