82 |
between requirements and design decisions is relatively |
between requirements and design decisions is relatively |
83 |
well developed [gotel94reqtracing-andalso-jarke98reqtracing]_. |
well developed [gotel94reqtracing-andalso-jarke98reqtracing]_. |
84 |
|
|
85 |
|
.. REF for j2sdk - probably no room.... XXX |
86 |
|
|
87 |
What is often missing is the connections between |
What is often missing is the connections between |
88 |
the design documentation and the embedded documentation. |
the design documentation and the embedded documentation. |
89 |
This can be daunting to a newcomer; consider the javadoc |
This can be daunting to a newcomer; consider the javadoc |
90 |
for the interface ``java.security.PublicKey`` in Sun's |
in Sun's Java2 SDK 1.4.1 |
91 |
Java2 SDK 1.4.1. |
for the interface ``java.security.PublicKey``. |
|
|
|
|
.. REF?. XXX |
|
|
|
|
92 |
While the class is easy to find through the package and class lists |
While the class is easy to find through the package and class lists |
93 |
when looking for a class to represent cryptographical public keys, |
when looking for a class to represent cryptographical public keys, |
94 |
the javadoc is not terribly useful: there is no information |
the javadoc is not terribly useful: there is no information |
234 |
The implementation in Navidoc |
The implementation in Navidoc |
235 |
============================= |
============================= |
236 |
|
|
237 |
|
.. Navidoc is a modular tool, lightweight tool |
238 |
|
for implementing the above |
239 |
|
UML-based linking between design documents and low-level |
240 |
|
documentation. |
241 |
|
Navidoc itself does relatively little --- it is built on top |
242 |
|
of other tools with minimal effort as an experiment. |
243 |
|
|
244 |
|
The most complex component is our own language |
245 |
|
for describing simple UML diagrams --- none of the free software |
246 |
|
tools were suitable for our purposes. |
247 |
|
It is a language and not a graphical editor because for programmers, |
248 |
|
the main audience of the tool, point-and-click is often slower |
249 |
|
than simple description of the diagram. |
250 |
|
The structure and layout of the diagram are separated |
251 |
|
|
252 |
|
|
253 |
.. think, this should be much clearer :) But how to say everything shortly... |
.. think, this should be much clearer :) But how to say everything shortly... |
254 |
|
|
255 |
Navidoc, our implementation, is as a light-weight tool built on top of |
Navidoc, our implementation, is as a light-weight tool built on top of |
261 |
in the images. These diagrams embedded into target documents, allow easy traverse |
in the images. These diagrams embedded into target documents, allow easy traverse |
262 |
through all the participant nodes and backlink to the startup page holding |
through all the participant nodes and backlink to the startup page holding |
263 |
the original diagram. |
the original diagram. |
264 |
|
The automatically inserted images |
265 |
|
are scaled to half size, whereas in their "real" location |
266 |
|
in the design documentation the images are shown at their full size. |
267 |
|
|
268 |
.. After compiling, it creates imagemaps for every UML diagram to link |
.. After compiling, it creates imagemaps for every UML diagram to link |
269 |
diagrams' elements to corresponding source code documentation |
diagrams' elements to corresponding source code documentation |
273 |
|
|
274 |
.. we can only have very few references [fsf02categories]_ |
.. we can only have very few references [fsf02categories]_ |
275 |
|
|
276 |
|
.. - main parts: Docutils [goodger02docutils]_, lexical UML language |
277 |
|
|
278 |
|
.. Navidoc uses several free utilies to convert each |
279 |
|
textual |
280 |
|
|
281 |
|
.. The UML diagram descriptions are then converted |
282 |
|
into a set of imagemaps --- one |
283 |
|
for each target document since the current document is highlighted |
284 |
|
in the images with color and a dark, irregular line to draw |
285 |
|
the viewer's eye towards it. |
286 |
|
|
287 |
.. - main parts: Docutils [goodger02docutils]_, lexical UML language |
.. - main parts: Docutils [goodger02docutils]_, lexical UML language |
288 |
|
|
289 |
.. No space for this, I wager |
.. No space for this, I wager |