On 6 September 2013 14:28, Petr Prikryl <prik...@skil.cz> wrote:
> Yongwei Wu wrote:
>> >> I really like to be able to show all data members in the diagram
>> >> without documenting them....
>> >
>> > Then you should set EXTRACT_PRIVATE to YES.
>>
>> You missed the "without documenting them" part :-).
>>
>> It is arguable that the original behaviour might be better. People
>> normally want to hide the private data members from documentation, but
>> the purpose of the collaboration diagram is to show the relationship
>> between this class and other objects. To put it to the extreme: In a
>> well-designed class, all data members are normally private; does it
>> mean that the collaboration diagram will NOT show anything then?
>
> Well, but does it make sense to generate a documentation without
> documenting anything?
My intention is just show how the class relates to (collaborates with)
other classes. Showing that class A associates with class B is one
thing, but showing that I have a data member called blah of type B in
class A (and requiring people to document it) is another.
> It may be difficult to judge without the real example, but...
>
> If you want to show the implementation internals (like the private
> members), you probably want to tell the programmer
> also what are they good for. If you want to hide the implementation
> (i.e. document only the API), then you also want to hide the internal
> collaboration. (Say, you want to hide it because it is subject
> to changes.)
It makes some sense to me, but, again, there is a subtle difference
between telling people that class A collaborates with class B and
telling people that class A has a data member named blah is of type B.
To give a fake example which is somewhat real, how do you want to document this:
template <class T>
class shared_ptr {
...
}
Does it make sense to show that shared_ptr collaborates with T without
documenting all the implementation details about shared_ptr's private
members?
> To summarize, it is natural--in my opinion--not to show the collaboration
> diagram for hidden functionality; or, it is natural to show also
> the documentation for the revealed parts of the collaboration
> graph.
>
> You may consider to generate several versions of the documentation:
> one of the end user, one for third party programmers (API), and
> one for you with the smallest details.
I can see it is not an easy call. Does it make sense to add a new
option for the collaboration diagram, something like
UNDOC_MEMBERS_IN_COLLAB_DIAGRAM or PRIVATE_MEMBERS_IN_COLLAB_DIAGRAM?
Best regards,
Yongwei
--
Wu Yongwei
URL: http://wyw.dcweb.cn/
------------------------------------------------------------------------------
Learn the latest--Visual Studio 2012, SharePoint 2013, SQL 2012, more!
Discover the easy way to master current and previous Microsoft technologies
and advance your career. Get an incredible 1,500+ hours of step-by-step
tutorial videos with LearnDevNow. Subscribe today and save!
http://pubads.g.doubleclick.net/gampad/clk?id=58041391&iu=/4140/ostg.clktrk
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
