[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink short-paper.rst
From: |
Tuomas J. Lukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink short-paper.rst |
Date: |
Tue, 20 May 2003 15:18:25 -0400 |
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
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/08
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/19
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst,
Tuomas J. Lukka <=
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/20
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Tuomas J. Lukka, 2003/05/21
- [Gzz-commits] manuscripts/UMLLink short-paper.rst, Asko Soukka, 2003/05/21