commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sébastien Brisard <sebastien.bris...@m4x.org>
Subject Re: [all] displaying some class and sequence diagrams for our components
Date Tue, 21 Aug 2012 06:50:20 GMT
Hi Luc,

2012/8/20 Luc Maisonobe <Luc.Maisonobe@free.fr>
>
> Le 20/08/2012 15:52, Simone Tripodi a écrit :
> > Hi Gary!
> >
> >> I still like the idea! I was hoping at an automagic solution ;)
> >
> > Me too! :)
>
> I have used several tools that were able to do such automatic diagrams
> generation. All tools that support roundtrip engineering should be able
> to do so. The free software tools I used are for example papyrus and
> topcased. I also used non-free tools for the same purpose.
>
> The result is *never* good.
>
> Of course, the result is theoretically accurate, it represents the
> current status of the code well, but it is completely useless and
> unreadable. I use diagrams mainly to explain something to the readers,
> to show the important stuff, to help them identify the fundamental
> aspects that may be completely hidden in a maze of implementation details.
>
> Automatic tools are not intelligent enough to identify what is
> meaningful and important and what should be discarded. If you look at
> some of the diagrams in the example pages I posted, you will see
> comments like "many methods not shown for clarity purposes". An
> automatic tool would not do that and would display all methods equally.
> Sometimes, I even suppress the method signature and show only the name,
> as the signature is irrelevant to understand the concept and would
> clutter the diagram.
>
> >
> > The only kind of "automagic" product I found was Objectaid for
> > Eclipse, but unfortunately
> >
> >  * it is (was, at the time of experimenting) not possible to have that
> > tool included in the build;
> >
> >  * it is specific IDE oriented (Eclipse)
> >
> >  * it requires a minimum of human-interaction - automatically arranged
> > layout could suck
> >
> >  * it is not completely free - license expires :( I tried to contact
> > them to obtain a license for OSS projects only, but did not success...
> >
> > This is a sample[1] a made for an assignment - it looks pretty good :P
>
> Sorry, I don't think so. There are too many things in this diagram, we
> don't know what the use links are for, the complete list of enumeration
> constants is too large ...
>
> This one of the reasons I like a small tool like plantuml. You can
> specify what you want to show and what is irrelelvant for a specific
> diagram. In fact, for one package or even one class, I often draw
> several different diagrams that focus on different aspects in different
> parts of the documentation, as these aspects are explained one after the
> other, not all together.
>
> So I understand this point of view is clearly not shared and I will
> therefore not include these diagrams in the documentation.
>
I wouldn't drop it that quickly! It seems to be a very interesting
idea. I'm certainly not an expert on UML, but I found these diagrams
useful, *when they are properly cleaned-up*. CM is a large library,
and the online documentation could benefit from these diagrams. Also,
it could be a useful tool for our own design discussions. So if other
people in CM agrees, I'm quite willing to give a try to the tool your
pointing at.

Sébastien
> best regards,
> Luc
>
> >
> > best,
> > -Simo
> >
> > [1] http://simonetripodi.github.com/shs/images/http-apis.png
> >
> > http://people.apache.org/~simonetripodi/
> > http://simonetripodi.livejournal.com/
> > http://twitter.com/simonetripodi
> > http://www.99soft.org/
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message