commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [all] displaying some class and sequence diagrams for our components
Date Wed, 22 Aug 2012 14:52:19 GMT
On 8/22/12 12:15 AM, Luc Maisonobe wrote:
> Hi Sébastien,
>
> Le 21/08/2012 08:50, Sébastien Brisard a écrit :
>> 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.
> Then we are back to square one: can such diagrams be generated by the
> automated maven build on all platforms, and if not should we generate
> them by ourselves on our own development platforms and provide both the
> source script and the generated image in the release source distribution?

I like the idea of including comprehensible UML as part of the
documentation for our components.  I am skeptical of being able to
maintain this automagically at build time / between releases,
however.  I will have a look at the tools mentioned in this thread
and see if I can use them to restore the [pool] UML that I dropped
due to laziness.  For [math], I would see it as an improvement if we
just incorporated relevant UML into the user guide.  One thing we
should verify is that the licensing of whatever tools we use does
not forbid ASL licensing of generated artifacts.

Phil
>
> best regards,
> Luc
>
>> 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
>>
>>
>
> ---------------------------------------------------------------------
> 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