/[gzz]/manuscripts/UMLLink/article.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/article.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.95 by tuukkah, Sat Feb 15 22:06:32 2003 UTC revision 1.96 by tuukkah, Sat Feb 15 22:20:22 2003 UTC
# Line 326  language [java-ref]_, the software devel Line 326  language [java-ref]_, the software devel
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.
# Line 342  in Table [ref-documentations]: Line 342  in Table [ref-documentations]:
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     +------------------------------+----------------------------------+     +------------------------------+----------------------------------+
# Line 374  in Table [ref-documentations]: Line 374  in Table [ref-documentations]:
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
# Line 400  We believe that the design documentation Line 398  We believe that the design documentation
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

Legend:
Removed from v.1.95  
changed lines
  Added in v.1.96

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26