[Gzz-commits] manuscripts/UMLLink umllink.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/01/22 16:11:28

Modified files:
        UMLLink        : umllink.rst 

Log message:
        reorging

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.34 
manuscripts/UMLLink/umllink.rst:1.35
--- manuscripts/UMLLink/umllink.rst:1.34        Wed Jan 22 16:07:44 2003
+++ manuscripts/UMLLink/umllink.rst     Wed Jan 22 16:11:28 2003
@@ -2,8 +2,8 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.34 2003/01/22 21:07:44 tjl Exp $
-:Last-Modified: $Date: 2003/01/22 21:07:44 $
+:Stamp: $Id: umllink.rst,v 1.35 2003/01/22 21:11:28 tjl Exp $
+:Last-Modified: $Date: 2003/01/22 21:11:28 $
 
 Issues
 ======
@@ -170,30 +170,6 @@
 the software engineering documentation
 is divided into two classes:
 
-The two types of documentation are complementary.
-
-+----------------------------------------+----------------------------------------------+
-|       Design docs                      |           Javadoc                   
         |
-+----------------------------------------+----------------------------------------------+
-|                                        |                                     
         |
-| - good overall picture.                |  - easy to find a given class,      
         |
-|                                        |    easy to check all methods        
         |
-|                                        |                                     
         |
-| - little detail,                       |  - detailed                         
         |
-|                                        |                                     
         |
-| - may be slightly outdated at          |  - methods and classes *always* up 
to        |
-|   any particular time.                 |    date (generated from source),    
         |
-|                                        |    doc comments also usually        
         |
-|                                        |                                     
         |
-| - hard to find explanations            |  - no overall picture of classes' 
roles      |
-|   for a particular class.              |                                     
         |
-|                                        |                                     
         |
-| - UML diagrams                         |                                     
         |
-|                                        |                                     
         |
-| - written and organized by humans      |                                     
         |
-|                                        |                                     
         |
-+----------------------------------------+----------------------------------------------+
-
 Javadoc
 
  - fully generated documentation from javadoc comments
@@ -202,15 +178,6 @@
    + the javadoc output filestructure follows the
      hierarchical tree structure of java packages and classes
 
- + hypertext disorientation problem still exists
-
-   Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: 
-   Cognitive Mapping and Navigation in a Hypertext Environment. 
-   In R. McAleese, & C. Green (Eds.), Hypertext: Theory into 
-   Practice (105-125), Oxford: Intellect Limited. 
-   (code in JYU-lib: "MK TIE HYPER")
-
-
 Architectural docs with UML diagrams: 
 
 
@@ -236,8 +203,43 @@
  - Include PEGs: possibly not-yet accepted or not-yet implemented proposals 
    for architectural changes.
 
+
+The two types of documentation are complementary, as demonstrated in the 
following table..
+
++----------------------------------------+----------------------------------------------+
+|       Design docs                      |           Javadoc                   
         |
++----------------------------------------+----------------------------------------------+
+|                                        |                                     
         |
+| - good overall picture.                |  - easy to find a given class,      
         |
+|                                        |    easy to check all methods        
         |
+|                                        |                                     
         |
+| - little detail,                       |  - detailed                         
         |
+|                                        |                                     
         |
+| - may be slightly outdated at          |  - methods and classes *always* up 
to        |
+|   any particular time.                 |    date (generated from source),    
         |
+|                                        |    doc comments also usually        
         |
+|                                        |                                     
         |
+| - hard to find explanations            |  - no overall picture of classes' 
roles      |
+|   for a particular class.              |                                     
         |
+|                                        |                                     
         |
+| - UML diagrams                         |                                     
         |
+|                                        |                                     
         |
+| - written and organized by humans      |                                     
         |
+|                                        |                                     
         |
++----------------------------------------+----------------------------------------------+
 "Obvious" question: can we increase the overall value by
 interconnecting the two?
+
+Architectural docs easily left in the dark reaches of the filesystem,
+not used as often as javadocs.
+
+ + hypertext disorientation problem still exists
+
+   Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: 
+   Cognitive Mapping and Navigation in a Hypertext Environment. 
+   In R. McAleese, & C. Green (Eds.), Hypertext: Theory into 
+   Practice (105-125), Oxford: Intellect Limited. 
+   (code in JYU-lib: "MK TIE HYPER")
 
 
 Design