[Gzz-commits] manuscripts/UMLLink article.rst

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/02/15 17:20:23

Modified files:
        UMLLink        : article.rst 

Log message:
        Background twids

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.95&tr2=1.96&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.95 
manuscripts/UMLLink/article.rst:1.96
--- manuscripts/UMLLink/article.rst:1.95        Sat Feb 15 17:06:32 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 17:20:22 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.95 2003/02/15 22:06:32 tuukkah Exp $
+.. :Stamp: $Id: article.rst,v 1.96 2003/02/15 22:20:22 tuukkah Exp $
 
 .. Points for HT people
    ====================
@@ -326,7 +326,7 @@
 divided into two major domains: the design documentation and
 Javadoc [friendly95javadoc]_. The design documents cover the most
 important architectural features and are written either before coding
-(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). 
 Javadoc,
 on the other hand, is a detailed and fully generated documentation from
 javadoc comments of each class and method in the Java source code.
@@ -342,18 +342,18 @@
    +------------------------------+----------------------------------+
    | Design documentation         | Javadoc                          |
    +==============================+==================================+
-   | good overall picture.        | easy to find a given class,      |
+   | good overall picture         | easy to find a given class,      |
    |                              | easy to check all methods        |
    +------------------------------+----------------------------------+
-   | little detail,               | detailed                         |
+   | little detail                | detailed                         |
    +------------------------------+----------------------------------+
    | may be slightly outdated at  | methods and classes *always*     |
-   | any particular time.         | up to date (generated from       |
+   | any particular time          | up to date (generated from       |
    |                              | source), doc comments also       |
    |                              | usually                          |
    +------------------------------+----------------------------------+
    | hard to find explanations    | no overall picture of classes'   |
-   | for a particular class.      | roles                            |
+   | for a particular class       | roles                            |
    +------------------------------+----------------------------------+
    | UML diagrams                 | ---                              |
    +------------------------------+----------------------------------+
@@ -374,23 +374,21 @@
 During coding, the Javadoc documentation is often
 necessary, but the design documentation is easily left in the
 dark reaches of the filesystem. It could be argued that the reason for
-design documents being left unused is that relevant parts linked to
+design documents being left unused is that parts related to
 ongoing work are hard to find. 
 
-For example, when referring to the Javadoc on how to use some API,
-one often comes across an interface which is of the type that
-one would like to obtain from somewhere, but unless someone
+For example, when referring to the Javadoc on how to use some interface,
+one often would like to know how to obtain an object which implements said
+interface, but unless someone
 has explicitly written the instructions into the doc comments,
 the Javadoc will only explain how the interface is used.
-What is exasperates this situation is the certainty 
-that in the design document, there surely is a diagram and a section
-which talks about the issue but finding them will take time.
-
-The distinct pieces (Javadoc and the
-design documentation) cannot seen as a whole. 
-
-The obvious question, then, is: can we increase the overall value by 
hyperlinking the 
-two distinct pieces of documentation? 
+What exasperates this situation is the certainty 
+that in the design document there surely is a diagram and a section
+which talks about the issue, but finding them will take time.
+
+The distinct pieces (Javadoc and the design documentation) cannot seen as a 
+whole. The obvious question, then, is: can we increase the overall value by 
+hyperlinking the two distinct pieces of documentation? 
 
 When looking at a design document, jumping to the Javadocs to get the
 details would be useful, and when looking at a Javadoc, it would be
@@ -400,10 +398,9 @@
 made easily reachable from relevant parts of Javadoc. 
 
 This is the
-starting point for the Free Software toolchain we developed in this
-article: a toolchain for bidirectional linking between design
-documentation and Javadoc, using UML diagrams as multi-ended nexus
-links.
+starting point for the Free Software toolchain we developed: a toolchain 
+for bidirectional linking between design
+documentation and Javadoc, using UML diagrams as multi-ended links.
 
 
 Structure design