326 |
divided into two major domains: the design documentation and |
divided into two major domains: the design documentation and |
327 |
Javadoc [friendly95javadoc]_. The design documents cover the most |
Javadoc [friendly95javadoc]_. The design documents cover the most |
328 |
important architectural features and are written either before coding |
important architectural features and are written either before coding |
329 |
(for design) or after (for exposition or of the architecture or refactoring design). |
(for design) or after (for exposition of the architecture or refactoring design). |
330 |
Javadoc, |
Javadoc, |
331 |
on the other hand, is a detailed and fully generated documentation from |
on the other hand, is a detailed and fully generated documentation from |
332 |
javadoc comments of each class and method in the Java source code. |
javadoc comments of each class and method in the Java source code. |
342 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
343 |
| Design documentation | Javadoc | |
| Design documentation | Javadoc | |
344 |
+==============================+==================================+ |
+==============================+==================================+ |
345 |
| good overall picture. | easy to find a given class, | |
| good overall picture | easy to find a given class, | |
346 |
| | easy to check all methods | |
| | easy to check all methods | |
347 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
348 |
| little detail, | detailed | |
| little detail | detailed | |
349 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
350 |
| may be slightly outdated at | methods and classes *always* | |
| may be slightly outdated at | methods and classes *always* | |
351 |
| any particular time. | up to date (generated from | |
| any particular time | up to date (generated from | |
352 |
| | source), doc comments also | |
| | source), doc comments also | |
353 |
| | usually | |
| | usually | |
354 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
355 |
| hard to find explanations | no overall picture of classes' | |
| hard to find explanations | no overall picture of classes' | |
356 |
| for a particular class. | roles | |
| for a particular class | roles | |
357 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
358 |
| UML diagrams | --- | |
| UML diagrams | --- | |
359 |
+------------------------------+----------------------------------+ |
+------------------------------+----------------------------------+ |
374 |
During coding, the Javadoc documentation is often |
During coding, the Javadoc documentation is often |
375 |
necessary, but the design documentation is easily left in the |
necessary, but the design documentation is easily left in the |
376 |
dark reaches of the filesystem. It could be argued that the reason for |
dark reaches of the filesystem. It could be argued that the reason for |
377 |
design documents being left unused is that relevant parts linked to |
design documents being left unused is that parts related to |
378 |
ongoing work are hard to find. |
ongoing work are hard to find. |
379 |
|
|
380 |
For example, when referring to the Javadoc on how to use some API, |
For example, when referring to the Javadoc on how to use some interface, |
381 |
one often comes across an interface which is of the type that |
one often would like to know how to obtain an object which implements said |
382 |
one would like to obtain from somewhere, but unless someone |
interface, but unless someone |
383 |
has explicitly written the instructions into the doc comments, |
has explicitly written the instructions into the doc comments, |
384 |
the Javadoc will only explain how the interface is used. |
the Javadoc will only explain how the interface is used. |
385 |
What is exasperates this situation is the certainty |
What exasperates this situation is the certainty |
386 |
that in the design document, there surely is a diagram and a section |
that in the design document there surely is a diagram and a section |
387 |
which talks about the issue but finding them will take time. |
which talks about the issue, but finding them will take time. |
388 |
|
|
389 |
The distinct pieces (Javadoc and the |
The distinct pieces (Javadoc and the design documentation) cannot seen as a |
390 |
design documentation) cannot seen as a whole. |
whole. The obvious question, then, is: can we increase the overall value by |
391 |
|
hyperlinking the two distinct pieces of documentation? |
|
The obvious question, then, is: can we increase the overall value by hyperlinking the |
|
|
two distinct pieces of documentation? |
|
392 |
|
|
393 |
When looking at a design document, jumping to the Javadocs to get the |
When looking at a design document, jumping to the Javadocs to get the |
394 |
details would be useful, and when looking at a Javadoc, it would be |
details would be useful, and when looking at a Javadoc, it would be |
398 |
made easily reachable from relevant parts of Javadoc. |
made easily reachable from relevant parts of Javadoc. |
399 |
|
|
400 |
This is the |
This is the |
401 |
starting point for the Free Software toolchain we developed in this |
starting point for the Free Software toolchain we developed: a toolchain |
402 |
article: a toolchain for bidirectional linking between design |
for bidirectional linking between design |
403 |
documentation and Javadoc, using UML diagrams as multi-ended nexus |
documentation and Javadoc, using UML diagrams as multi-ended links. |
|
links. |
|
404 |
|
|
405 |
|
|
406 |
Structure design |
Structure design |