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

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/05/28 05:16:07

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        fixed some typos in intro, changed java.security.PublicKey example

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

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.37 
manuscripts/UMLLink/short-paper.rst:1.38
--- manuscripts/UMLLink/short-paper.rst:1.37    Mon May 26 09:36:43 2003
+++ manuscripts/UMLLink/short-paper.rst Wed May 28 05:16:07 2003
@@ -77,7 +77,7 @@
 for several languages 
 [devanbu99chime-andalso-friendly95javadoc-andalso-heesch03doxygen]_.
 Similarly, requirements tracing --- managing relations
-between requirements and design decisions is relatively
+between requirements and design decisions --- is relatively
 well developed [gotel94reqtracing]_.
 
 ..  Gotel could be a little critical for that context,
@@ -92,21 +92,21 @@
 This can be daunting to a newcomer; consider the javadoc
 in Sun's Java2 SDK 1.4.1
 for the interface ``java.security.PublicKey``.
-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, without much contextual information
-about the importance of the methods - the methods for 
-creating a ``PublicKey`` are listed alongside the methods
-that return a ``PublicKey`` contained in another object..
+While the class is easily found through the package and class lists
+when looking for a class representing cryptographical public keys,
+the javadoc is not terribly useful: it lacks the information
+there on how to create objects that implement this interface.
+Currently, the only relevant links are on an accompanying ``Use`` page,
+which lists all the occurrences of this class elsewhere in the 
+documentation.
+Further, those lists lack information about the contextual importance of 
+the methods --- the methods for 
+creating a ``PublicKey`` are listed alongside eg. the methods
+that return a ``PublicKey`` contained in another object.
 
 Far more helpful would be a link to the design
-documentation, even just a diagram of what the intended
-uses or lifespans of classes implementing this interface
-are and how one creates them. 
+documentation, even just a diagram showing the intended
+uses or lifespans of related objects and how one creates the objects.
 These diagrams certainly exist for all properly managed 
 medium-to-large scale software projects --- the problem is getting
 them to where it matters without having to manually insert