[Gzz-commits] manuscripts/UMLLink short-paper.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/05/20 15:18:25

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        Some text

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.11&tr2=1.12&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.11 
manuscripts/UMLLink/short-paper.rst:1.12
--- manuscripts/UMLLink/short-paper.rst:1.11    Tue May 20 14:04:41 2003
+++ manuscripts/UMLLink/short-paper.rst Tue May 20 15:18:25 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.11 2003/05/20 18:04:41 tjl Exp $
+.. $Id: short-paper.rst,v 1.12 2003/05/20 19:18:25 tjl Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -35,6 +35,7 @@
    Requirements traceability research
    http://www.sei.cmu.edu/str/descriptions/reqtracing_body.html
    http://www.cis.ksu.edu/~hankley/d841/Fa99/chap2.htm
+
    http://www.computer.org/proceedings/apsec/0915/09150206abs.htm?SMSESSION=NO
 
    http://www.computer.org/software/so1994/s4104abs.htm
@@ -52,7 +53,8 @@
 
 Software projects manage a large base of evolving documentation, whose
 parts are
-inter-related on many levels. Design documentation shows
+inter-related on many levels. 
+Design documentation shows
 architectural views on a more general level, while 
 the source code (in e.g. Java and nowadays often also C++)
 contains
@@ -67,6 +69,33 @@
 a solved problem 
 for several languages 
 [friendly95javadoc-andalso-heesch03doxygen-andalso-devanbu99chime]_.
+Similarly, requirements tracing --- managing relations
+between requirements and design decisions is relatively
+well developed [XXX]_.
+
+What is often missing is the connections between
+the design documentation and the embedded documentation.
+This can be daunting to a newcomer; consider the javadoc
+for the interface ``java.security.PublicKey`` in Sun's
+Java2 SDK 1.4.1 at
+``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
+XXXREF
+While the class is easy to find through the package and class lists
+when looking for a class to represent cryptographical public keys,
+the javadoc is not terribly useful: there is no information
+there on how one may create objects that implement this interface.
+The only way to find this out is to click on the ``Use`` link
+which lists all the occurrences of this class as method
+return values or parameters.
+However, what would really help would be a link to the design
+documentation, even just a UML diagram of what the intended
+uses or lifespans of classes implementing this interface
+are and how one creates them.
+
+In this article, we discuss Navidoc: a system that, given design
+documentation with marked-up UML diagrams, inserts the UML
+diagrams into the classes' javadocs to function as spatial menus.
+
 
 
 ..  There exist plenty of documentation tools to generate well navigable
@@ -89,14 +118,14 @@
    quostions alike. Check at first the keywords given by referees
    of UMLLink article.
 
-Connecting the distinct areas is essential because it could help new
-developers in getting productive and supports development processes
-where both design and implementation change continuously.
-Our solution to link distinct software development documentations
-together is to base it on UML diagrams which are drawn on design
-documentation to abstract the system under development. We believe
-that advantages of using UML diagrams as navigational aids clearly beat
-the minor additional work that is needed.
+..  Connecting the distinct areas is essential because it could help new
+    developers in getting productive and supports development processes
+    where both design and implementation change continuously.
+    Our solution to link distinct software development documentations
+    together is to base it on UML diagrams which are drawn on design
+    documentation to abstract the system under development. We believe
+    that advantages of using UML diagrams as navigational aids clearly beat
+    the minor additional work that is needed.
 
 .. It could be that UML diagrams won't be optimal for navigation of hypertext 
and
    they won't cover the whole documentation. 
@@ -229,7 +258,6 @@
 Our approach is different from most tools,
 which rely more on automatically generated links [XXX],
 or inserting connections to the source code [devanbu99chime]_.
-
 
 .. - future
     * fenfire