107 |
* UML diagrams: distinct context for Java classes and packages and relevant |
* UML diagrams: distinct context for Java classes and packages and relevant |
108 |
architectural documentation; spatial menu; also node (XXX multi-ended nexus |
architectural documentation; spatial menu; also node (XXX multi-ended nexus |
109 |
links) |
links) |
110 |
|
|
111 |
* generated by our UML tool from our UML diagram description language |
* generated by our UML tool from our UML diagram description language |
112 |
|
|
113 |
* Cross-reference by Javadoc: cheap cross-link |
* Cross-reference by Javadoc: cheap cross-link |
124 |
Diagrams |
Diagrams |
125 |
======== |
======== |
126 |
|
|
|
|
|
|
|
|
127 |
Introduction |
Introduction |
128 |
============ |
============ |
129 |
|
|
130 |
Software projects manage a large base of evolving documentation, which is |
Software projects manage a large base of evolving documentation, which |
131 |
inter-related on many levels. Design documentation gives architectural views |
is inter-related on many levels. Design documentation gives |
132 |
on more general level, while the program code source files give all the minute |
architectural views on more general level, while the program code |
133 |
details on how the computer should act and contain embedded documentation for |
source files give all the minute details on how the computer should |
134 |
human-readability. Although these two parts of documentation are |
act and contain embedded documentation for human-readability. Although |
135 |
semantically dependent, in practice they are often linked scarcely -- if at |
these two parts of documentation are semantically dependent, in |
136 |
all. |
practice they are often linked scarcely -- if at all. |
137 |
|
|
138 |
The Unified Modeling Language (UML) is the standard way to XXX visually |
The Unified Modeling Language (UML) is the standard way to visually |
139 |
describe software constructs in diagrams _[#]. It was originally developed |
describe software constructs in diagrams |
140 |
for descriptions |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
141 |
on an abstract level (many constructs cannot be directly expressed in |
developed for descriptions on an abstract level (many constructs |
142 |
any programming language) _[#], but current trend is to use it also on the |
cannot be directly expressed in any programming language) |
143 |
concrete |
[booch-jacobson-rumbaugh98uml-user-guide]_, but current trend is to |
144 |
level, as to fully unify the architectural documentation and program code: the |
use it also on the concrete level, as to fully unify the architectural |
145 |
program code might be generated from highly detailed diagrams _[#], or exact |
documentation and program code: the program code might be generated |
146 |
diagrams be produced from the source code _[#]. |
from highly detailed diagrams |
147 |
|
[harrison-barton-raghavachari00uml-to-java]_, or exact diagrams be |
148 |
|
produced from the source code |
149 |
.. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide? |
[pierce-tilley02connecting-documentation-rose]_. |
|
|
|
|
.. [#] booch-jacobson-rumbaugh-uml-user-guide p.15 |
|
|
booch-jacobson-rumbaugh-uml-reference-manual p.4 |
|
|
|
|
|
.. [#] harrison-barton-raghavachari00uml-to-java |
|
|
|
|
|
.. [#] pierce-tilley02connecting-documentation-rose |
|
150 |
|
|
151 |
|
.. uml user guide p.XXX |
152 |
|
.. uml user guide p.12 |
153 |
|
|
154 |
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 |
155 |
architecture on general level. UML functions as a common language for |
architecture on general level. UML functions as a common language for |
158 |
human-drawn diagrams to exact illustrations matching source code to |
human-drawn diagrams to exact illustrations matching source code to |
159 |
every detail: |
every detail: |
160 |
|
|
161 |
"You draw diagrams to visualize a system from different |
"You draw diagrams to visualize a system from different |
162 |
perspectives, so a diagram is a projection into a system. |
perspectives, so a diagram is a projection into a system. |
163 |
For all but the most trivial systems, a diagram represents an elided |
For all but the most trivial systems, a diagram represents an elided |
164 |
view of the elements that make up a system." [#]_ |
view of the elements that make up a system." |
165 |
|
[booch-jacobson-rumbaugh98uml-user-guide]_ |
166 |
: (could other stakeholders be identified and described to some extent |
|
167 |
somewhere? it might be interesting to think also towards users/customers, |
.. from uml user guide p.24 |
168 |
who in some methods (ways of using XP) control use cases themselves) |
|
169 |
|
.. (could other stakeholders be identified and described to some |
170 |
: UML is easier to read than write. Also, non-programmers often don't have |
extent somewhere? it might be interesting to think also towards |
171 |
the insight needed to directly take part in designing (even in use cases)? |
users/customers, who in some methods (ways of using XP) control |
172 |
|
use cases themselves) |
173 |
.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24 |
|
174 |
|
.. UML is easier to read than write. Also, non-programmers often |
175 |
|
don't have the insight needed to directly take part in designing |
176 |
In this article, we present a navigational aid which connects the two distinct |
(even in use cases)? |
177 |
areas of documentation, and its fairly easy implementation which |
|
178 |
supplements the toolchain of other Free Software [] we use. The other |
In this article, we present a navigational aid which connects the two |
179 |
documentation tools can already generate web pages, and the tool injects the |
distinct areas of documentation, and its fairly easy implementation |
180 |
added linking to those HTML files. The tool automatically generates the |
which supplements the toolchain of other Free Software |
181 |
linking deduced from readily available UML diagram descriptions in our |
[fsf02categories]_ we use. The other documentation tools can already |
182 |
documentation. This means the tool is deployable without further authoring. |
generate web pages, and the tool injects the added linking to those |
183 |
|
HTML files. The tool automatically generates the linking deduced from |
184 |
It turns out that in addition to working as multi-ended links, the diagrams |
readily available UML diagram descriptions in our documentation. This |
185 |
each generate a new navigational context within the target nodes. We found |
means the tool is deployable without further authoring. |
186 |
this useful because the Javadoc tool, which we use for program code |
|
187 |
documentation, does not promote un-hierarchical coherence. |
It turns out that in addition to working as multi-ended links, the |
188 |
|
diagrams each generate a new navigational context within the target |
189 |
|
nodes. We found this useful because the Javadoc tool, which we use for |
190 |
|
program code documentation, does not promote un-hierarchical |
191 |
|
coherence. |
192 |
|
|
193 |
: Javadoc has plenty of unhierarchical links, but they are not meaningful, |
.. Javadoc has plenty of unhierarchical links, but they are not meaningful, |
194 |
they don't give the documentation any structure. |
they don't give the documentation any structure. |
195 |
|
|
196 |
: XXX move last chapter away from Introduction? |
.. XXX move last chapter away from Introduction? |
197 |
|
|
198 |
Implementation |
Implementation |
199 |
============== |
============== |
200 |
|
|
201 |
Eventually, we found no Free Software [XXX] tools which would |
Eventually, we found no Free Software [fsf02categories]_ tools which |
202 |
fulfill our needs. Therefore, we decided to proceed with our own |
would fulfill our needs. Therefore, we decided to proceed with our own |
203 |
implementation. There were several goals to be achieved. The tool had |
implementation. In addition to the previously discussed goals of the |
204 |
to: |
documentation as whole, there were also several implementation related |
205 |
|
goals to be achieved. The tool had to: |
206 |
|
|
207 |
- be tidy and light-weight |
- be tidy and light-weight |
208 |
|
|
216 |
|
|
217 |
Up to this article all steps except the last one are implemented. The |
Up to this article all steps except the last one are implemented. The |
218 |
existing tools we selected as the basis for our documentation tool are: |
existing tools we selected as the basis for our documentation tool are: |
219 |
Javadoc [XXX], Docutils [XXX], and our own UML diagram description |
Javadoc [friendly95javadoc]_, Docutils [XXX], and our own UML diagram description |
220 |
tool. Further, the UML tool uses several free utilies to convert |
tool. Further, the UML tool uses several free utilies to convert |
221 |
each lexical UML description into final *Portable Network |
each lexical UML description into final *Portable Network |
222 |
Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost), |
Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost), |
224 |
manipulation toolkit. Besides Javadoc, all tools used are Free |
manipulation toolkit. Besides Javadoc, all tools used are Free |
225 |
Software. |
Software. |
226 |
|
|
|
|
|
227 |
??After the plugin interface is created, the documentation |
??After the plugin interface is created, the documentation |
228 |
linking utility could also be used with other HTML documentation |
linking utility could also be used with other HTML documentation |
229 |
generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it? |
generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it? |