[cfe-commits] Request feedback for new diagnostic feature - template type diffing

[Chandler Carruth]

On Mon, Aug 29, 2011 at 6:59 PM, Douglas Gregor <dgregor at apple.com> wrote:

>
> On Aug 29, 2011, at 6:30 PM, Chandler Carruth wrote:
>
> On Mon, Aug 29, 2011 at 6:10 PM, Douglas Gregor <dgregor at apple.com> wrote:
>
>>
>> On Aug 23, 2011, at 9:45 PM, Richard Trieu wrote:
>>
>> > I have been working on a new feature for diagnostic messages.  When a
>> diagnostic contains two template types, give additional notes to show which
>> part of the template is different.  For large templates, this will help
>> users more quickly determine what is wrong with the template.
>> >
>> > For example:
>> >
>> > template <typename T1, typename T2> class A {};
>> > template <typename T1> class B {};
>> > template <typename T1> class C {};
>> > template <typename T1> class D {};
>> >
>> > void foo(A<B<C<D<const int> > >, B<C<D<const double> > > > F) {}
>> >
>> > void bar() {
>> >   foo(A<B<C<D<int> > >, B<C<const double> > >());;
>> > }
>> >
>> > would give the error:
>> >
>> > type-diff.cc:26:3: error: no matching function for call to 'foo'
>> >   foo(A<B<C<D<int> > >, B<C<const double> > >());;
>> >   ^~~
>> > type-diff.cc:23:6: note: candidate function not viable: no known
>> conversion from 'A<B<C<D<int> > >, B<C<const double> > >' to
>> >       'A<B<C<D<const int> > >, B<C<D<const double> > > >' for 1st
>> argument;
>> > void foo(A<B<C<D<const int> > >, B<C<D<const double> > > > F) {}
>> >      ^
>> >
>> > It's hard to see exactly what's different from 'A<B<C<D<int> > >,
>> B<C<const double> > >' and 'A<B<C<D<const int> > >, B<C<D<const double> > >
>> >'
>> >
>> > With template type diffing, additional notes are emitted to show the
>> difference.  It now becomes:
>> >
>> > type-diff.cc:26:3: error: no matching function for call to 'foo'
>> >   foo(A<B<C<D<int> > >, B<C<const double> > >());;
>> >   ^~~
>> > type-diff.cc:23:6: note: candidate function not viable: no known
>> conversion from 'A<B<C<D<int> > >, B<C<const double> > >' to
>> >       'A<B<C<D<const int> > >, B<C<D<const double> > > >' for 1st
>> argument;
>> > void foo(A<B<C<D<const int> > >, B<C<D<const double> > > > F) {}
>> >      ^
>> > type-diff.cc:23:6: note: Type 'C<const double>' is different from type
>> 'C<D< >>'
>> > type-diff.cc:23:6: note: Type 'D<int>' is different from type 'D<const
>> int>'
>> >
>> > I have attached a patch with an early prototype of this feature and
>> would appreciate any feedback.  Currently, the extra notes are only
>> displayed for this one note, but should be easy enough to extend to other
>> places.  There's also a test case included to show some other examples of
>> this feature.  Let me know what you think about it.
>>
>> Interesting. I like the general idea, but I'm very worried that displaying
>> this information via extra notes is going to introduce a significant amount
>> of console spew. Especially when we're dealing with displayed candidate
>> sets, where we already have a large number of notes.
>>
>> What we really want is to draw the user's eye to the differences between
>> two similar types. Could we take advantage of the colorized console messages
>> to highlight the differences between two similar types within the message
>> text itself, so it doesn't cost us any more screen real estate?
>
>
> Several people mentioned this idea... I'm not sure it really works for all
> use cases though.
>
> One of the common problems cited is that the template names are so long
> that they wrap across multiple lines. I think drawing the users eye to the
> two pieces that are different is going to be hard even with underlining or
> bolding or other formatting.
>
>
> With the current, note-based scheme, I need to first look at the types
> mentioned as different and then search for where they occur in the long,
> wrapped diagnostic text above. They may even occur multiple times in the
> diagnostic text, so I need to figure out which occurrences the warning is
> talking about. If we annotate the diagnostic text directly with bold or
> color, we get all of this information in one place, and there's no hunting.
>
> The other interesting aspect is that these notes don't add as much screen
> real estate as many others -- they're essentially guaranteed to not show the
> code snippet, and to be very short, so they don't line wrap a lot.
>
>
> I agree they aren't as bad as full-length notes, but I maintain that it's
> still a lot of information to add to an already-verbose diagnostic… and I
> think coloring (when it's available) is actively better.
>
> Finally, nothing says we have to do one or the other. We could do both, and
> allow people to enable or disable them. This seems particularly appealing to
> me, as for non-console users, there are much more intuitive ways to display
> this information.
>
>
> Well, sure. We can represent this information in some way that allows
> coloring or bold when available on the console (which I still think is
> preferable), and provide some other markup (possibly including multiple
> notes) for non-console output.
>

I'm really uncomfortable with this direction, despite not disagreeing with
any of your points here. I completely agree about the drawbacks of separate
notes, and why colors can be very nice, just so we're on the same page.

My problem is this: thus far, Clang's colors, bold, and other markup of the
textual output don't add any information, they just make the information
displayed easier to read. I like that distinction, because we have a lot of
users who will at some points not have color or bold available when looking
at the text. This happens either due to disabilities, deficient terminals,
terminal preferences, ssh silliness, or because the diagnostics have gone
through a layer of textual logging that tried to strip escape codes. Lots of
different reasons this can happen.

As a result, I've found it very important that the user can usually get the
full benefit of the improved diagnostic even w/o these nice-to-have markups.
This is the first time (I think) that we're adding a really significant
amount of logic to convey information that would be lost without the colors
/ markup. (Another interesting example is that we break the underlining of
source ranges into ~s on a separate line in ascii art rather than using the
underlining escape codes.)

Can you think up a way to not have to make this compromise? That is, could
we present this information in a way that didn't require colors or other
special terminal features *and* didn't have the downside of notes
(searching, etc)? I haven't been able to, but that would be my
preference. While I would love to take advantage of a more rich medium when
available (*cough* IDEs make this easy *cough*), I'd like to get as much of
this benefit into the plain-old-text output as possible, with the
understanding that we have a lot of users which will loose some or all of
the markup we apply to the text...


The current output matches almost exactly what several users told us they
did in order to read the existing diagnostics: they cut/pasted the type into
an editor, and deleted the similar parts. My intuition is that users will
actually like having these elements broken out, as well as having the
complete types, but it seems like our intuition about how users are reading
these diagnostics differs. Do you happen to have any data? I know I don't,
and sadly I'm not even sure how to acquire any which makes this a hard
debate to really have unless we can come up with a clearly superior
alternative to all those currently on the table.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20110829/c2510d5c/attachment.html>