commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [all] displaying some class and sequence diagrams for our components
Date Wed, 22 Aug 2012 15:08:57 GMT
On 22 August 2012 15:52, Phil Steitz <phil.steitz@gmail.com> wrote:
> 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.

And please could any diagrams include date and the software version
for which they were generated?

> 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
>

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


Mime
View raw message