commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Luc Maisonobe <Luc.Maison...@free.fr>
Subject Re: [all] displaying some class and sequence diagrams for our components
Date Mon, 20 Aug 2012 19:03:45 GMT
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.

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


Mime
View raw message