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 |
|
:Last-Modified: $Date$ |
6 |
|
|
7 |
Introduction |
Introduction |
8 |
============ |
============ |
9 |
|
|
10 |
UML, the blah, has recently become blah blah |
UML, the blah, has recently become blah blah |
11 |
|
|
12 |
Javadoc, the hypertext documentation tool that comes with |
Javadoc, the hypertext documentation tool that comes with |
13 |
Java, is ... |
Java (trademark of Sun Microsystems, Javadoc is distributed only |
14 |
|
as part of Java, non-free), is ... |
15 |
Easy to check methods, hard to get overall picture. |
Easy to check methods, hard to get overall picture. |
16 |
Because doc generated from source, the class, method, field |
Because doc is generated from source, the class, method, field |
17 |
names are always up-to-date(!!) |
names are always up-to-date(!!) |
18 |
|
|
19 |
Architectural docs using UML: little detail, may be |
Architectural docs using UML: little detail, may be |
20 |
slightly outdated at any particular time. However, |
slightly outdated at any particular time. However, |
21 |
good overall picture. |
good overall picture. Even outdated but well simplified diagram |
22 |
|
is better than too detailed, automaticly up-to dated and reverse |
23 |
|
engineered diagram. |
24 |
|
|
25 |
|
Some statements from the UML book (Booch, Jacobson, Rumbaugh, p.6) |
26 |
|
"A model is a simplification of reality." |
27 |
|
"We build models so that we can better understand the system |
28 |
|
we are developing." |
29 |
|
|
30 |
In this article, we present the tools we developed |
In this article, we present the tools we developed |
31 |
for using UML diagrams as multiple-ended hyperlinks |
for using UML diagrams as multiple-ended hyperlinks |
32 |
between the architectural documents and javadoc. |
between the architectural documents and javadoc. |
33 |
|
|
|
|
|
34 |
Recommended sources for references: IEEE, ACM |
Recommended sources for references: IEEE, ACM |
35 |
|
|
36 |
"Automatically connecting documentation to code with rose" uses reverse engineering |
- Borge's "taxonomy" for animals; |
37 |
http://doi.acm.org/10.1145/584955.584979 |
http://www.multicians.org/thvv/borges-animals.html |
38 |
"Mapping UML to JAVA", uh... this meant generating code :/ |
- !! A Taxonomy of Link Types; |
39 |
http://doi.acm.org/10.1145/353171.353184 (Use this link to Bookmark this page) |
http://www.workpractice.com/trigg/thesis-chap4.html |
40 |
|
|
41 |
|
Thinking about linking... at first we do have UML->reST and |
42 |
|
UML->javadoc links. Because of embedding diagrams implicitly |
43 |
|
into target documents we can see linking also as |
44 |
|
bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc. |
45 |
|
|
46 |
|
Mapping our links to types defined by Trigg: |
47 |
|
|
48 |
|
reST<->reST Alternate View (this occurs, when the same diagram is |
49 |
|
explicitly referred in two or more architectural documents) |
50 |
|
javadoc<->javadoc AlternativeView? (We can browse through all classes, which |
51 |
|
are part of the diagram.) |
52 |
|
UML->reST Detail->Summary |
53 |
|
UML->Javadoc General->Spesific or Summary->Detail |
54 |
|
|
55 |
|
Trigg classifies the following type-pairs for bi-directional links, which can are |
56 |
|
interpreted oppositionally depending on the direction |
57 |
|
|
58 |
|
Generalization/Specification |
59 |
|
Abstraction/Example |
60 |
|
Formalization/Application |
61 |
|
Summarization/Detail |
62 |
|
Simplification/Complication |
63 |
|
|
64 |
|
Could Generalization/Specification be best for reST<->Javadoc. |
65 |
|
|
66 |
|
- Labeled, typed links as cues when reading hypertext documents; http://search.epnet.com/direct.asp?an=9702214682&db=afh |
67 |
|
|
68 |
|
- Automatically connecting documentation to code with rose; http://doi.acm.org/10.1145/584955.584979 |
69 |
|
reverse engineering diagrams from existing source code |
70 |
|
- Mapping UML to JAVA; http://doi.acm.org/10.1145/353171.353184 |
71 |
|
generating Java code from UML |
72 |
|
|
73 |
Previous work |
Previous work |
74 |
============= |
============= |
81 |
- though, because we are coders, we would prefer UML language |
- though, because we are coders, we would prefer UML language |
82 |
over menus and dialogs when creating UML objects |
over menus and dialogs when creating UML objects |
83 |
+ we need critic for direct manipulation! |
+ we need critic for direct manipulation! |
84 |
+ though, direcmanipulation is only relevant solution for |
+ though, directmanipulation is only relevant solution for |
85 |
replacing already created objects |
replacing already created objects |
86 |
|
|
87 |
Dia (drawing, generating code templates) |
Dia (drawing, generating code templates) |
97 |
|
|
98 |
Doc++ - autogen not-so-useful diagrams |
Doc++ - autogen not-so-useful diagrams |
99 |
|
|
|
MetaEdit (from JYU) |
|
|
- meta CASE tool; could be made to create code from the diagrams |
|
|
- used for domain spesific languages |
|
100 |
|
|
101 |
MetaPhor, hypertext in soft. devel? |
MetaPhor, hypertext in soft. devel? (http://metaphor.it.jyu.fi/ |
102 |
|
- bi-directional linking of CASE-tool documents/objects (e.g. double |
103 |
|
clicking an object opens more detailed diagram, backlink could |
104 |
|
be found from popup-menu... anyway, a lot of menus to select |
105 |
|
objects for linking or already linked objects to show) |
106 |
|
- Reminds me linking mindmaps in MindManager... |
107 |
|
- MetaEdit+ |
108 |
|
+ meta CASE tool; could be made to generate code from the diagrams |
109 |
|
+ could be used to create domain spesific languages, when generating |
110 |
|
code can really work |
111 |
|
|
112 |
This page lists a lot of UML tools: |
This page lists a lot of UML tools: |
113 |
http://plg.uwaterloo.ca/~migod/uml.html |
http://plg.uwaterloo.ca/~migod/uml.html |
209 |
Implementation |
Implementation |
210 |
============== |
============== |
211 |
|
|
212 |
-free software ketju chain |
-free software chain |
213 |
-flow diagram |
-flow diagram |
214 |
|
|
215 |
|
|