136 |
Abstract |
Abstract |
137 |
======== |
======== |
138 |
|
|
139 |
|
We describe automatic linking of design documentation to javadoc |
140 |
|
through UML diagrams embedded in both, acting as nexus links. |
141 |
|
|
142 |
XXX !!! |
XXX !!! |
143 |
|
|
144 |
Introduction |
Introduction |
147 |
Software projects manage a large base of evolving documentation, which |
Software projects manage a large base of evolving documentation, which |
148 |
is inter-related on many levels. Design documentation gives |
is inter-related on many levels. Design documentation gives |
149 |
architectural views on a more general level, while the program code |
architectural views on a more general level, while the program code |
150 |
source files give all the minute details on how the computer should |
source files contain interfaces and embedded documentation |
151 |
act and contain embedded documentation for human-readability. Although |
giving all the minute details on how the computer should act. Although |
152 |
these two parts of documentation are semantically dependent, linking |
these two parts of documentation are semantically dependent, linking |
153 |
them is tedious -- if even possible -- when they are authored using different |
them is tedious -- if even possible -- when they are authored using different |
154 |
software. |
software. |
158 |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
159 |
developed for descriptions on an abstract level (many constructs |
developed for descriptions on an abstract level (many constructs |
160 |
cannot be directly expressed in any programming language) |
cannot be directly expressed in any programming language) |
161 |
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but current |
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current |
162 |
trend is to use it also on the concrete level, as to fully unify the |
trend is to use it also on the concrete level, as to fully unify the |
163 |
architectural documentation and program code: the program code might |
architectural documentation and program code: the program code might |
164 |
be generated from highly detailed diagrams |
be generated from highly detailed diagrams |
165 |
[harrison-barton-raghavachari00uml-to-java]_, or exact diagrams be |
[harrison-barton-raghavachari00uml-to-java]_, or diagrams |
166 |
produced from the source code |
may be produced from the source code |
167 |
[pierce-tilley02connecting-documentation-rose]_. |
[pierce-tilley02connecting-documentation-rose]_. |
168 |
|
|
169 |
Against this trend, we still use UML only to plan and document our software |
Against this trend, we still use UML only to plan and document our software |
170 |
architecture on a general level. UML functions as a common language for |
architecture on a general level. UML functions as a common language for |
171 |
communication within our software development team, and in this purpose we |
communication within our software development team, and for this purpose we |
172 |
prefer better abstracted and more comprehensible |
prefer human-drawn diagrams that abstract from the gory details |
173 |
human-drawn diagrams to exact illustrations matching source code to |
of code to be more comprehensible to us: |
|
every detail: |
|
174 |
|
|
175 |
"You draw diagrams to visualize a system from different |
"You draw diagrams to visualize a system from different |
176 |
perspectives, so a diagram is a projection into a system. |
perspectives, so a diagram is a projection into a system. |