[Gzz-commits] manuscripts/UMLLink umllink.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/01/21 09:17:25

Modified files:
        UMLLink        : umllink.rst 

Log message:
        scratching

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

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.27 
manuscripts/UMLLink/umllink.rst:1.28
--- manuscripts/UMLLink/umllink.rst:1.27        Tue Jan 21 08:23:00 2003
+++ manuscripts/UMLLink/umllink.rst     Tue Jan 21 09:17:25 2003
@@ -2,14 +2,14 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Last-Modified: $Date: 2003/01/21 13:23:00 $
+:Last-Modified: $Date: 2003/01/21 14:17:25 $
 
 Introduction
 ============
 
 UML, the blah, has recently become blah blah
 
-UML book (Booch, Jacobson, Rumbaugh, p.6)
+UML book (Booch, Jacobson, Rumbaugh)
 p.24: 
 
     "You draw diagrams to visualize a system from different
@@ -17,7 +17,6 @@
     For all but the most trivial systems, a diagram represents an elided
     view of the elements that make up a system."
 
-
 Recently, various approaches have been developed towards
 unifying software architecture documents and code (REFS)
 
@@ -37,6 +36,7 @@
 
 - creating UML diagrams to natural part of our design (pegboard) and
   documenting (architecture docs) process
+
   + how our development process diffs from "the common way"?
   + too small budget for large tookillls like Rational Rose
 
@@ -51,7 +51,6 @@
  - how rational rose links diagrams into code and documentation?
 
  - Automatically connecting documentation to code with rose; 
-   http://doi.acm.org/10.1145/584955.584979
    reverse engineering diagrams from existing source code 
 
  - though, because we are coders, we would prefer UML language
@@ -67,7 +66,7 @@
  - could be used instead of metapost, but
    direct manipulation problem again
 
-doxygen
+Doxygen
 
  - can generate useless diagrams from the code class hierarchy
  - should describe somewhere why these are useles... 
@@ -80,15 +79,22 @@
    be found from popup-menu... anyway, a lot of menus to select
    objects for linking or already linked objects to show)
 
- - Reminds me linking mindmaps in MindManager... 
-
  - MetaEdit+
 
    + meta CASE tool; could be made to generate code from the diagrams 
-
    + could be used to create domain spesific languages, when generating
      code can really work
 
+   Kalle Lyytinen, Pekka Kerola. (1994). MetaPHOR Project: Final 
+   Report. Department of Computer Science and Information Systems. 
+   University of Jyväskylä. <http://metaphor.it.jyu.fi/loppurap/>
+
+This page lists a lot of UML tools:
+http://plg.uwaterloo.ca/~migod/uml.html
+
+Other non-commercial documentation tools:
+http://www.stack.nl/~dimitri/doxygen/links.html
+
 Javadoc
 -------
 
@@ -96,40 +102,63 @@
 Java (trademark of Sun Microsystems, Javadoc is distributed only
 as part of Java, non-free), is ...
 
+doc++ a free software alternative for javadoc
 
 Setting of problem
 ==================
 
-javadoc
+Javadoc
 
-    - Easy to check methods, hard to get overall picture.
+ - fully generated documentation from development
+   project's java source code
 
-    - Because doc is generated from source, the class, method, field
-      names are always up-to-date(!!)
+ - easy to find a given class, easy to check methods
+   + the javadoc output filestructure follows the
+     hierarchical tree structure of java packages and classes
+
+ - the location in class-tree is well shown everywhere in
+   javadoc, but the role of single class or package in
+   developing software remains unknown
+
+   + hard to get overall picture.
+   + 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")
 
-    - easy to find a given class
+ - because doc is generated from source, the class, method, field
+   names and their inline documentation are always up-to-date(!!)
 
 Architectural docs with UML diagrams: 
 
-    - diagrams are from human to human
-         + we don't wan to generate diagrams from the code or generate
-           code from the diagrams
-         + generated diagrams are too detailed to be beneficial
+ - diagrams are from human to human
+
+   + we don't wan to generate diagrams from the code or generate
+     code from the diagrams
+   + generated diagrams are too detailed to be beneficial
+   + basic architectural diagrams should be done before code anyway
 
-    - good overall picture. 
+ - good overall picture. 
 
-    - little detail, 
+ - little detail, 
 
-    - may be slightly outdated at any particular time. 
+ - may be slightly outdated at any particular time. 
+      
+   + why even outdated but well simplified diagram
+     is better than too detailed, automaticly up-to dated 
+     and reverse engineered diagram.
 
-    - Even outdated but well simplified diagram
-      is better than too detailed, automaticly up-to dated and reverse
-      engineered diagram.
+ - distinct from the javadoc, hard to find explanations
+   for a particular class.
 
-    - distinct from the javadoc, hard to find explanations
-      for a particular class.
+   + and if documentation is outdated some particular classes
+     maybe don't even exist anymore!
 
-    - these cover the most relevant parts from the architecture and the code
+ - these cover the most relevant parts from the architecture 
+   and the code
 
 The two types of documentation are complementary.
 
@@ -142,29 +171,29 @@
 
 What can we link?
 
- - Perspectives to UML class diagrams, or classifiers in general: 
-    Cook and Daniels, Designing Object Systems: Object-Oriented Modeling
-    with Syntropy. Prentice Hall, 1994. Referred in Fowler and Scott: UML 
distilled,
-    2nd ed., Addison-Wesley.
+ - Perspectives to UML class diagrams, or classifiers in general:
 
-       - Conceptual
+   Cook and Daniels, Designing Object Systems: Object-Oriented 
+   Modeling with Syntropy. Prentice Hall, 1994. 
+   Referred in Fowler and Scott: UML distilled,
+   2nd ed., Addison-Wesley.
 
-           - probably no links
+   - Conceptual
 
-       - Specification
-           
-           - can link Java interfaces
+     + probably no links for javadoc
+     + but we can still enhance the linking within
+       the architectural documentation
 
-       - Implementation
+   - Specification
+         
+     + can link Java interfaces
 
-           - can link all classes
+   - Implementation
 
-    - can be useful to link even concept with the class that eventually 
implemented
-      it.
+     + can link all classes
 
- - First stage: link only classifiers, and only where the author of the UML
-   diagram explicitly specified a link. In interaction diagrams, it's also easy
-   to find the relevant method from the javadoc.
+   - can be useful to link even concept with the class 
+     that eventually implemented it.
 
 Documentation's reader's point of view
 ---------------------------------------
@@ -173,65 +202,79 @@
 
 Step 0; distinct architecture documentation with UML diagrams and javadoc 
generated from the sourcecode.
 
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
+- UML diagrams in architecture documentation may link within architectural
+  documentation
+  
+  + objects in UML diagrams which represent parts of the 
+    documentation are linked to that parts of documentation
+
 Advantage over paper: NONE
 
 Step 1; links from architecture documentation's UML-diagrams into relevant 
javadoc class documentations
 
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-   + when only following dummy link into some part of 
-     javadoc tree, we would lost the class' context in the architecture
-     documentation we started
-
-Advantage over paper: MARGINAL: automatize cross-indexing
-
-Step 2; embedding UML-diagrams into javadoc, linking also them
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+- when we only follow some dummy directed link into some part of 
+  javadoc tree, we would lost the class' context in the architecture
+  documentation we left (and moved into javadoc)
 
-   + though, this is not yet enough, because we want to know
-      where classes are referred in architecture documentation
+- objects in UML diagrams which represent java classes 
+  are linked to javadoc of those classes
 
-   + infuriating to the user that the diagram allows navigation
-     between *almost* all contexts it is shown in.
+Advantage over paper: MARGINAL: automatize cross-indexing
 
-   + diagrams a little cluttery 
+Step 2; embedding UML-diagrams into javadoc, embedded UML-diagrams' objects 
also work as links
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+- now all objects in UML diagrams could be linked within architecture
+  documentation, from architectural documentation to javadoc, within 
+  javadoc or from javadoc to architecture documentation
+
+- though, this is not yet enough, because we want to know
+  where classes are referred in architecture documentation, to be
+  more exact: where those diagrams implicitly embedded into javadoc
+  are explicitly included
+
+  + "focus+context menu"-metaphor for diagrams needs that we can
+    "step back" from class documentation back to architecture
+    documentation
 
 Advantage over paper: SOME: see the contexts of a class,
 traverse them
 
 Step 3; backlinks to the architecture documentation
 """""""""""""""""""""""""""""""""""""""""""""""""""
-   + "focus+context menu"-metaphor for diagrams 
+- "focus+context menu"-metaphor for diagrams 
 
-       + we highlight the "focused" element 
-         of the diagram
-   
-       + we can
-         "step back" from class documentation back to architecture
-         documentation. 
+   + we highlight the "focused" element of the diagram
+        
+- we can "step back" from class documentation back to architecture
+  documentation. 
 
-    + all this (UML and rerer backlinks)  drawn into diagram for consistency
+  + all this (UML and refer backlinks) drawn into diagram for consistency
+    reasons; this supports "focus+context menu"-metaphor
 
-    + because we can now go to the architectural document from the javadoc,
-      we can reduce the size of the diagram in the javadoc by 50%.
+  + because we can now go to the architectural document from the javadoc,
+    we can reduce the size of the diagram in the javadoc by 50%.
+   
+    + technical note: hovering mouse over diagram will show 
+      class names even on diminished diagrams
 
 Advantage over paper: MAJOR: multi-end links easily traversable,
 structure can be understood
 
-
 Documentation's developer's point of view
 -----------------------------------------
 
 Goals:
 
-    - small, incremental changes to existing javadoc / other documentation
+ - small, incremental changes to existing javadoc / other documentation
 
-    - Low threshold for writing new documentation, diagrams etc.
+ - Low threshold for writing new documentation, diagrams etc.
 
 reST's filosophy
 
  - indentation for blocks
  - robust for erros
  - "natural" to write
- - "ASCII layout" (our UML-language is an exception)
+ - "ASCII layout" (our UML-language is an exception, which is discussed later)
 
 Why UML-language
 
@@ -247,44 +290,52 @@
  - only explicit link from diagram object to the class it represents is
    obligatory, all other are implicit
 
-
-
 UML diagram component
     
-    - not strictly necessary; could have used another editor
+ - not strictly necessary; could have used another editor
+
+ - problem: direct manipulation of UML diagrams very clunky
+
+ - users are programmers --> allow a simple programming language
+
+ - placement: currently metapost; looking at ways to make 
+  interactively editable.
 
-    - problem: direct manipulation of UML diagrams very clunky
+  + elements are easy to create by script language
+  + graphical placing could need an GUI
 
-    - users are programmers --> allow a simple programming language
+ - minimun barrier to drawing a even small diagram to make
+   document more clear
 
-    - placement: currently metapost; looking at ways to make interactively
-      editable.
-      + elements are easy to create by script language
-      + graphical placing could need an GUI
+ - link diagrams' objects to code documentation, which 
+   they represent
 
-- minimize the cap of drawing a even small diagram to make
-  document more clear
-- link diagrams' objects to code documentation, which 
-  they represent
-- implicitly embed diagrams into relevant code documentation, and
-  backlink code documentation to design documentation
-- make diagrams work as context+focusing menus to the code documentation
+ - implicitly embed diagrams into relevant code documentation, and
+   backlink code documentation to design documentation
 
+ - if diagrams try to link objects, which don't exist (e.g. removed
+   Java class), the linking objects will be specially marked 
+   e.g. colored red
 
-UML diagram of how architectural documents, UML diagrams and javadoc pages 
work.
-Instead of browsing only in one direction, all associations shown in the 
diagram
-should be browsable in either direction!
+ - make diagrams work as context+focusing menus to the code documentation
 
-UML diagrams act as multi-ended nexus links, bringing together all documents
-they relate to. They function like navigation bars on the WWW, except that
-the same page may have several of them.
+UML diagram of how architectural documents, UML diagrams and javadoc 
+pages work. Instead of browsing only in one direction, all associations 
+shown in the diagram should be browsable in either direction! 
+
+ + HTML/WWW don't support bi-directional links
+
+UML diagrams act as multi-ended nexus links, bringing together all 
+documents they relate to. They function like navigation bars on the 
+WWW, except that the same page may have several of them.
 
 Analysis from a hypertext theory point of view
 ==============================================
 
 - Borges's "taxonomy" for animals;
   http://www.multicians.org/thvv/borges-animals.html
-- !! A Taxonomy of Link Types;
+
+- A Taxonomy of Link Types;
   http://www.workpractice.com/trigg/thesis-chap4.html
   
   Thinking about linking... at first we do have UML->reST and 
@@ -292,28 +343,37 @@
   into target documents we can see linking also as 
   bi-directional reST<->javadoc, reST<->reST, and javadoc<->javadoc.
 
-  Mapping our links to types defined by Trigg:
-
-    reST<->reST  Alternate View (this occurs, when the same diagram is 
-                 explicitly referred in two or more architectural documents)
+  Mapping our links to types defined by Trigg (Normal links)::
 
-    javadoc -> javadoc AlternativeView? (We can browse through all classes, 
which
-                     are part of the diagram.)
+    reST <-> reST  Alternate View
+                   
+                   this occurs, when the same diagram is 
+                   explicitly referred in two or more architectural 
+                   documents
+
+    javadoc -> javadoc Alternate View? 
+               
+                       We can browse through all classes, which
+                      are part of the diagram. Inside the diagram 
+                       only focusing changes.
 
     UML in javadoc -> reST    Detail->Summary
 
     UML in reST -> Javadoc General->Spesific or Summary->Detail
 
-  Trigg classifies the following type-pairs for bi-directional links, which 
can are
-  interpreted oppositionally depending on the direction
+  Trigg classifies the following type-pairs for bi-directional 
+  links, which can are interpreted oppositionally depending on 
+  the direction
+
+    - Generalization/Specification
+    - Abstraction/Example 
+    - Formalization/Application
+    - Summarization/Detail
+    - Simplification/Complication
 
-  Generalization/Specification
-  Abstraction/Example 
-  Formalization/Application
-  Summarization/Detail
-  Simplification/Complication
+  ::
 
-  Could Generalization/Specification be best for reST<->Javadoc.  
+     reST <-> javadoc Generalization/Specification  
 
 From our point of view, the links in the last version cease to be "links"
 and the UML diagrams become objects in their own right.
@@ -323,53 +383,53 @@
 
 Goals:
     
-    - light-weight
+ - light-weight
 
-    - using existing free software tools
+ - using existing free software tools
 
-    - plugins for documentation tool (javadoc replacement)
-      outputs: easily adaptable to others.
+ - plugins for documentation tool (javadoc could be replaced
+   with free software, several documentation tools could be used
+   simultanously...)
 
--free software chain
+ - outputs: easily adaptable to others (editing the source).
 
--flow diagram
+ - free software chain
+
+ - flow diagram of the implementation
 
 Practical use
 =============
 
 - n classes, n diagrams, n pages architecture documentation, and works
+
 - we develop open software => good documentation is needed for
   lowering threshold for new people
 
 Acknowledgments
 ===============
+
 antont
 
 Conclusion
 ==========
 
-
-- need easier placing (but not automatic)
+- need easier placing (but still not automatic)
 
 - metapost's erros are fuzzy, when using scripting language for
   drawing diagrams, we need clearer errors
 
 - it's possible that we change metapost for something else
 
-  + getting rid of problem with error messages and slow compiling process
-
+  + getting rid of problem with fuzzy error messages and slow compiling process
   + we can still continue using our UML language
 
   - less power: with mp, can draw arbitrary stuff on the diagrams
     as well; this is sometimes useful, but sometimes not desirable.
 
-- all in all, this is temporary system: using web pages for the presentation/UI
-  layer of a hypertext system is useful and standard but very limiting.
-  The system we are using these tools to develop is intended for better
-  user interfaces to similar ...
-
-- Currently, we only link UML classifiers to Java classes. Methods could
-  also be linked, especially in interaction diagrams.
-
-
+- all in all, this is temporary system: using web pages for the 
+  presentation/UI layer of a hypertext system is useful and standard 
+  but very limiting. The system we are using these tools to develop is 
+  intended for better user interfaces to similar ...
 
+- Currently, we only link UML classifiers to Java classes. Methods 
+  could also be linked, especially in interaction diagrams.