RE: [Doxygen-users] Class collaboration [LONG]

[Kris T. <kri...@ic...>]

This is fun indeed. Maybe not practical, but ok...

> DEFINITION:
> 	Class A is CONTAINED in class B if and only if class B has
> an instance (not pointer or reference) member variable to class A.
>
fine for me

> DEFINITION:
> 	Class A is USED-BY class B if and only if in some member
> functions of class B invokes a member function of class A.
>
> 	(I say member function, because we make all our member variables
> private, right?)
>
fine for me as well. Except that I would include member variables in the
definition. That way, you wouldn't have to add anything specific for friends
below (if it's a friend, but doesn't use any of its members, there wasn't a
point in having it a friend anyway).

Here's one practical problem for doxygen: to decide on this, it would have
to parse the actual C++ code, and in particular the implementations of the
member functions. I don't think doxygen does this, and I don't think it
would be easy. Sounds much more like real compilation to me.

In particular, for nearly all purposes, you can get away with doxygening
only the .h files (except of you put doxygen comments in .cxx).

> 	struct A { void Foo(void){} };
>
> CASE I (Instance)
> 	1) class B { A a; void Bar(void) {a.Foo();} };
> 	2) class B { A a[10]; void Bar(void) {a[0].Foo();} };  //  ??
> 	3) class B { void Bar(A a) {a.Foo();} };
> CASE II (Pointer)
> 	1) class B { A *a; void Bar(void) {a->Foo();} };
> 	2) class B { void Bar(A *a) {a->Foo();} };
> CASE III (Reference)
> 	1) class B { A &a; void Bar(void) {a.Foo();} };
> 	2) class B { void Bar(A &a) {a.Foo();} };
>
> 	We need to be careful in handling cases II and III, because
> B does not necessarily invoke any public member function of A...
> However, in reality, Doxygen simply concludes that class A is USED-BY
> Class B in cases II.1 and III.1  It does not consider II.2 or III.2
> Perhaps it should?
>

I.2 seems an obvious candidate as well

>
> DEFINITION:
> 	Class A is DIRECTLY-RELATED to class B if and only if class
> A is CONTAINED in class B, or class A is USED-BY class B, or class
> B is a FRIEND to class A.
>

fine for me.


> CASE IV (Template)

tough and so on. But I'm afraid that if you don't handle it, a lot of my
code will not see any benefit if all this.

> >  "Is the result of a solution of the problem worth of the
> >   complexity of the solution?"
>
> 	Probably not...  Oh well, life is full of tradeoff's.  :)
>
if you ask me, it means that 'collaboration diagrams' are very diffiuclt to
make sensible. In such a case, it is better to disable them in my opinion.
Incomplete doc is more confusing than no doc.
In any case, I can get so graphs in my doc from doxygen nowadays that it all
looks stunning enough already!


> 	It has been fun typing this message.  Thank you for
> your time if you made it this far.

you're welcome.

Kris Thielemans
Imaging Research Solutions Ltd
Cyclotron Building
Hammersmith Hospital
Du Cane Road
London W12 ONN, United Kingdom


web site address:
http://www.irsl.org/~kris