[cfe-dev] -emit-html example

[Ted Kremenek]

On Apr 20, 2008, at 4:20 PM, Argiris Kirtzidis wrote:
> Chris Lattner wrote:
>> One of the spiffy things that Ted is doing with his static analysis  
>> stuff is having it emit reports in HTML.  A required part of this  
>> is just being able to turn code itself into HTML.  I think that the  
>> stuff clang is doing is pretty cool, so I thought I'd show an  
>> example.
>>
>> [.....]
>>
>> Anyway, give -emit-html a try, if you have ideas for making it  
>> better, it's really easy to improve: for example, the code to do  
>> the macro expansions is ~70 lines of commented code at the end of  
>> HTMLRewrite.
>
> Hey, this is awesome!
>
> I had an idea to generalize it a bit to allow for other uses of  
> source annotation. The attached patch adds a 'Annotate' library  
> which provides interfaces for source file annotation.
> There are an 'Annotator' class (derived from ASTConsumer) that  
> traverses the AST and dispatches annotations to a 'AnnotationClient'  
> object.
> HTMLPrinter becomes a specialized AnnotationClient that puts out a  
> html file and uses the annotations. Another kind of AnnotationClient  
> could be used by an IDE
> to syntax-colorize the displayed source file.
>
> As you can see from AnnotationClient interface, I added a  
> HighlightVar annotation. HTMLPrinter currently uses it to colorize  
> and create links on variable names that point to
> the variable declaration line. I attached gcc.html so you can see  
> how it works on 'gcc.c'.
>
> Let me know what you think!

Hi Argiris,

Sorry for the late reply to this email.  It's been a busy week, and I  
shouldn't have neglected getting back to you.

I took a look at this patch.  I like the low-level refactorings to the  
HTML rewriter API (e.g., adding HighlightKeyword).  This provides some  
nice cleanups that simplify the conceptual complexity of the code  
(particularly in SyntaxHighlight).  These aren't strictly necessary,  
but do but some structure into how we want to name HTML classes for  
span tags, etc.

While I appreciate it's clean design, I have to be honest that I'm not  
really sold (yet) on the Annotator class.  While I can envision that  
we will have multiple clients of the HTML rewriter (e.g., the HTML  
pretty-printer, the HTMLDiagnostics used by the static analysis  
engine, a doxygen-like documentation generator, and so on) these  
different clients will not necessarily fall into an ASTConsumer model,  
nor will this interface necessarily be the one they want.

Basically I'm not certain if it really solves a problem at this point,  
and right now adds an extra abstraction layer to implement the  
HTMLPrinter (something at its heart is very, very simple).  Right now  
we have two clients of the HTML Rewriter: one is an ASTConsumer, and  
the other is not.  I don't believe that an IDE would be an ASTConsumer  
(in the clang driver sense) either, but would rather interact with the  
clang libraries interactively to regenerate ASTs on-the-fly.

The nice thing about the "low-level" APIs in HTMLRewrite.h is that  
they make little assumption about the target application, but do the  
lion's share of the work when pretty-printing code to HTML without  
introducing an abstraction layer.  The result is that for the current  
clients of the HTML Rewrite API (HTMLPrinter and HTMLDiagnostics) the  
amount of code they do to perform HTML "tweaking" is small.  The  
HTMLPrinter has about 20-30 lines of code (which includes opening  
files and comments) and HTMLDiagnostics contains a little code for  
doing HTML work but this is proportional to the extra stuff that it  
outputs.

Don't get me wrong; I'm a big believer in refactoring and modular  
design.  I don't think the Annotator has a bad design, I just don't  
think it's necessary at this point, and I'd rather not add more  
abstraction unless its a clear benefit.

Ted