r180629 - document parsing. When a sub-class (c++ Objective-C) missing

[Dmitri Gribenko]

On Sat, Apr 27, 2013 at 1:24 AM, jahanian <fjahanian at apple.com> wrote:
> Why does this test use -ast-dump?  Usually c-index-test is used to
> test if comment is attached to something.  There are fewer CHECK lines
> that way.
>
>
> OK. I will add a c-index test (without removing the existing one which took
> quite time
> to get it right :).

That's exactly why c-index-test tests are preferred: they are more
maintainable.  So if you convert this file to c-index-test, just
remove the original test.

> Also, about the approach this patch implements -- while it makes sense
> in some cases, it can be confusing in most other situations.  For
> example:
>
> /// A window.
> class Window {};
> class Door {};
>
> class House : Window, Door {};
>
> 'House' will pick up the 'Window' comment, which is probably not what
> the user wants.
>
>
> You are right. There are cases which will not make sense. But, not knowing
> that, we pick the first
> one we see (which meets our user requirements). Generally, Important classes
> must have their own
> comments.

Right, in a well-designed and well-documented codebase all important
classes are documented.  But this is not true in many codebases one
can see in the wild.

If you decide that you really need to go this way (I don't think this
is a good approach, but anyway), please limit this to public
inheritance, which models is-a relationship.  It is semantically not
appropriate to check private and protected bases for documentation.
But private inheritance is not used much in C++, so this exclusion
will not help much to reduce confusion.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/