On 22 August 2012 15:52, Phil Steitz <phil.ste...@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.maison...@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-unsubscr...@commons.apache.org >>>>> For additional commands, e-mail: dev-h...@commons.apache.org >>>>> >>>>> >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>>> For additional commands, e-mail: dev-h...@commons.apache.org >>>> >>> >>> --------------------------------------------------------------------- >>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>> For additional commands, e-mail: dev-h...@commons.apache.org >>> >>> >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >> For additional commands, e-mail: dev-h...@commons.apache.org >> >> > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
