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