2 |
A free software toolchain for bidirectional linking between UML diagrams and Javadoc |
A free software toolchain for bidirectional linking between UML diagrams and Javadoc |
3 |
==================================================================================== |
==================================================================================== |
4 |
|
|
5 |
|
Introduction |
6 |
|
============ |
7 |
|
|
8 |
|
UML, the blah, has recently become blah blah |
9 |
|
|
10 |
|
Javadoc, the hypertext documentation tool that comes with |
11 |
|
Java, is ... |
12 |
|
Easy to check methods, hard to get overall picture. |
13 |
|
Because doc generated from source, the class, method, field |
14 |
|
names are always up-to-date(!!) |
15 |
|
|
16 |
|
Architectural docs using UML: little detail, may be |
17 |
|
slightly outdated at any particular time. However, |
18 |
|
good overall picture. |
19 |
|
|
20 |
|
In this article, we present the tools we developed |
21 |
|
for using UML diagrams as multiple-ended hyperlinks |
22 |
|
between the architectural documents and javadoc. |
23 |
|
|
24 |
|
|
25 |
Recommended sources for references: IEEE, ACM |
Recommended sources for references: IEEE, ACM |
26 |
|
|
27 |
"Automatically connecting documentation to code with rose" uses reverse engineering |
"Automatically connecting documentation to code with rose" uses reverse engineering |
60 |
- meta CASE tool; could be made to create code from the diagrams |
- meta CASE tool; could be made to create code from the diagrams |
61 |
- used for domain spesific languages |
- used for domain spesific languages |
62 |
|
|
63 |
|
MetaPhor, hypertext in soft. devel? |
64 |
|
|
65 |
This page lists a lot of UML tools: |
This page lists a lot of UML tools: |
66 |
http://plg.uwaterloo.ca/~migod/uml.html |
http://plg.uwaterloo.ca/~migod/uml.html |
67 |
|
|
74 |
Our developing steps: |
Our developing steps: |
75 |
|
|
76 |
- step 0; distinct architecture documentation with UML diagrams |
- step 0; distinct architecture documentation with UML diagrams |
77 |
and javadoc generated from the sourcecode |
and javadoc generated from the sourcecode. |
78 |
|
Advantage over paper: NONE |
79 |
- step 1; links from architecture documentation's UML-diagrams into |
- step 1; links from architecture documentation's UML-diagrams into |
80 |
relevant javadoc class documentations |
relevant javadoc class documentations |
81 |
+ when only following dummy link into some part of |
+ when only following dummy link into some part of |
82 |
javadoc tree, we would lost the class' context in the architecture |
javadoc tree, we would lost the class' context in the architecture |
83 |
documentation we started |
documentation we started |
84 |
|
Advantage over paper: MARGINAL: automatize cross-indexing |
85 |
- step 2; embedding UML-diagrams into javadoc, linking also them |
- step 2; embedding UML-diagrams into javadoc, linking also them |
86 |
+ though, this is not yet enough, because we want to know |
+ though, this is not yet enough, because we want to know |
87 |
where classes are referred in architecture documentation |
where classes are referred in architecture documentation |
90 |
documentation |
documentation |
91 |
- step 3; backlinks to the architecture documentation |
- step 3; backlinks to the architecture documentation |
92 |
+ all this (UML and rerer backlinks) drawn into diagram for consistency |
+ all this (UML and rerer backlinks) drawn into diagram for consistency |
93 |
|
Advantage over paper: MAJOR: multi-end links easily traversable, |
94 |
|
structure can be understood |
95 |
|
|
96 |
Documentation's developer's point of view |
Documentation's developer's point of view |
97 |
----------------------------------------- |
----------------------------------------- |
178 |
|
|
179 |
... |
... |
180 |
|
|
181 |
- easier placing (but not automatic) |
- need easier placing (but not automatic) |
182 |
- metapost's erros are fuzzy, when using scripting language for |
- metapost's erros are fuzzy, when using scripting language for |
183 |
drawing diagrams, we need clearer errors |
drawing diagrams, we need clearer errors |
184 |
- it's possible that we change metapost for something else |
- it's possible that we change metapost for something else |
185 |
+ getting rid of problem with error messages and slow compiling process |
+ getting rid of problem with error messages and slow compiling process |
186 |
+ we can still continue using our UML language |
+ we can still continue using our UML language |
187 |
|
- less power: with mp, can draw arbitrary stuff on the diagrams |
188 |
|
as well; this is sometimes useful, but sometimes not desirable. |
189 |
|
|
190 |
|
|
191 |
|
|