[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink article.rst
From: |
Tuukka Hastrup |
Subject: |
[Gzz-commits] manuscripts/UMLLink article.rst |
Date: |
Sat, 15 Feb 2003 17:20:23 -0500 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Tuukka Hastrup <address@hidden> 03/02/15 17:20:23
Modified files:
UMLLink : article.rst
Log message:
Background twids
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.95&tr2=1.96&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.95
manuscripts/UMLLink/article.rst:1.96
--- manuscripts/UMLLink/article.rst:1.95 Sat Feb 15 17:06:32 2003
+++ manuscripts/UMLLink/article.rst Sat Feb 15 17:20:22 2003
@@ -9,7 +9,7 @@
.. Alternative title: "Free Software toolchain for bidirectional
linking between UML diagrams and Javadoc"
-.. :Stamp: $Id: article.rst,v 1.95 2003/02/15 22:06:32 tuukkah Exp $
+.. :Stamp: $Id: article.rst,v 1.96 2003/02/15 22:20:22 tuukkah Exp $
.. Points for HT people
====================
@@ -326,7 +326,7 @@
divided into two major domains: the design documentation and
Javadoc [friendly95javadoc]_. The design documents cover the most
important architectural features and are written either before coding
-(for design) or after (for exposition or of the architecture or refactoring
design).
+(for design) or after (for exposition of the architecture or refactoring
design).
Javadoc,
on the other hand, is a detailed and fully generated documentation from
javadoc comments of each class and method in the Java source code.
@@ -342,18 +342,18 @@
+------------------------------+----------------------------------+
| Design documentation | Javadoc |
+==============================+==================================+
- | good overall picture. | easy to find a given class, |
+ | good overall picture | easy to find a given class, |
| | easy to check all methods |
+------------------------------+----------------------------------+
- | little detail, | detailed |
+ | little detail | detailed |
+------------------------------+----------------------------------+
| may be slightly outdated at | methods and classes *always* |
- | any particular time. | up to date (generated from |
+ | any particular time | up to date (generated from |
| | source), doc comments also |
| | usually |
+------------------------------+----------------------------------+
| hard to find explanations | no overall picture of classes' |
- | for a particular class. | roles |
+ | for a particular class | roles |
+------------------------------+----------------------------------+
| UML diagrams | --- |
+------------------------------+----------------------------------+
@@ -374,23 +374,21 @@
During coding, the Javadoc documentation is often
necessary, but the design documentation is easily left in the
dark reaches of the filesystem. It could be argued that the reason for
-design documents being left unused is that relevant parts linked to
+design documents being left unused is that parts related to
ongoing work are hard to find.
-For example, when referring to the Javadoc on how to use some API,
-one often comes across an interface which is of the type that
-one would like to obtain from somewhere, but unless someone
+For example, when referring to the Javadoc on how to use some interface,
+one often would like to know how to obtain an object which implements said
+interface, but unless someone
has explicitly written the instructions into the doc comments,
the Javadoc will only explain how the interface is used.
-What is exasperates this situation is the certainty
-that in the design document, there surely is a diagram and a section
-which talks about the issue but finding them will take time.
-
-The distinct pieces (Javadoc and the
-design documentation) cannot seen as a whole.
-
-The obvious question, then, is: can we increase the overall value by
hyperlinking the
-two distinct pieces of documentation?
+What exasperates this situation is the certainty
+that in the design document there surely is a diagram and a section
+which talks about the issue, but finding them will take time.
+
+The distinct pieces (Javadoc and the design documentation) cannot seen as a
+whole. The obvious question, then, is: can we increase the overall value by
+hyperlinking the two distinct pieces of documentation?
When looking at a design document, jumping to the Javadocs to get the
details would be useful, and when looking at a Javadoc, it would be
@@ -400,10 +398,9 @@
made easily reachable from relevant parts of Javadoc.
This is the
-starting point for the Free Software toolchain we developed in this
-article: a toolchain for bidirectional linking between design
-documentation and Javadoc, using UML diagrams as multi-ended nexus
-links.
+starting point for the Free Software toolchain we developed: a toolchain
+for bidirectional linking between design
+documentation and Javadoc, using UML diagrams as multi-ended links.
Structure design
- [Gzz-commits] manuscripts/UMLLink article.rst, (continued)
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuomas J. Lukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst,
Tuukka Hastrup <=
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuomas J. Lukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuomas J. Lukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Tuukka Hastrup, 2003/02/15
- [Gzz-commits] manuscripts/UMLLink article.rst, Asko Soukka, 2003/02/15