[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink umllink.rst
From: |
Asko Soukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink umllink.rst |
Date: |
Wed, 05 Feb 2003 20:19:49 -0500 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Asko Soukka <address@hidden> 03/02/05 20:19:49
Modified files:
UMLLink : umllink.rst
Log message:
steps
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.59&tr2=1.60&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.59
manuscripts/UMLLink/umllink.rst:1.60
--- manuscripts/UMLLink/umllink.rst:1.59 Tue Feb 4 11:23:31 2003
+++ manuscripts/UMLLink/umllink.rst Wed Feb 5 20:19:49 2003
@@ -2,7 +2,7 @@
A free software toolchain for bidirectional linking between UML diagrams and
Javadoc
====================================================================================
-:Stamp: $Id: umllink.rst,v 1.59 2003/02/04 16:23:31 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.60 2003/02/06 01:19:49 humppake Exp $
2nd round todo:
===============
@@ -306,13 +306,16 @@
cannot seen as whole. Therefore we should make them work as a whole.
"Obvious" question: can we increase the overall value by interconnecting the
-two distinct documentations?
+two distinct documentations?
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 useful
-to be able to see if any design documents refer to that class.
+to be able to see if any design documents refer to that class.
+We believe that the architecture document will be read more, after it's
+it's easily reachable from relevant parts of Javadoc.
This is the starting point for the toolchain developed in this article.
+
Design
======
@@ -377,64 +380,54 @@
Documentation's reader's point of view
---------------------------------------
-When developing
-
-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
+Into current state our documentation evolved through several distinct
+steps, which will be viewed first from the reader's and then from
+the developers point of view.
+
+**Step 0; In the beginning we had a distinct architecture documentation with
+UML diagrams and javadoc generated from the sourcecode.** There is probably
+the most common case. The both documentations could comprehensive and well
+navigable by their own, but their information is hard to combine, because
there
+is no crosslinking between them.
Advantage over paper: NONE
-Step 1; links from architecture documentation's UML-diagrams into relevant
javadoc class documentations
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-- 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)
-
-- objects in UML diagrams which represent java classes
- are linked to javadoc of those classes
+**Step 1; Links from architecture documentation's UML diagrams are created
+into relevant javadoc class documentation.** After the first step javadoc was
+finally reachable from architecture documentation only by clicking relevant
+classes or packages within embedded UML diagrams. Though, after moving to
+the javadoc the context in architectural documentation could be immidiately
+lost. Also there was no links from javadoc to arcitecture documentation.
Advantage over paper: MARGINAL: automatize cross-indexing
-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
+**Step 2; UML-diagrams are implicitly embedded into javadoc and embedded
+UML-diagrams' objects also work as links.** After the second step we had
+diagrams working as menus between the objects that appeared in diagrams.
+Though, even a single diagram could be used to traverse between all the
+documentation pages referred in the diagram, it the original page including
+the diagram was unreachable from the diagram itself.
Advantage over paper: SOME: see the UML diagram contexts of a class,
traverse them
-Step 3; backlinks to the architecture documentation
-"""""""""""""""""""""""""""""""""""""""""""""""""""
-- "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.
-
- + 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%.
-
- + technical note: hovering mouse over diagram will show
- link target class names even on diminished diagrams
+**Step 3; Backlinks to the architecture documentation that include diagrams
+is added.** Finally it's possible to "step back" from class documentation
+back to architecture documentation. After backlinks to the architecture
+documentation is added, a single diagram include an linked object for all
+architecture documentation and javadoc pages, where it is explicitly or
+implicitly included. Even the architectural documentation pages were not parts
+of the original UML diagrams, they are included in the final image on top of
the
+UML diagram. Putting all these into same graphical images make the all links
+look a consistent whole - like a spatial menu. [XXXREFS??] Also the element in
+image representing the current documenta page is focused and target of
+focus+contex menu is achieved.
+
+Because the original location on the diagrams is easily reachable from its
+every implicit occurerrence in javadoc or in architecture documentation, the
+size of the implicitly embedded diagram could be reduced by 50%. The name
+of diagram object is also shown, hovering the pointing device over diagram -
also
+on diminished diagrams.
Advantage over paper: MAJOR: multi-end links easily traversable,
structure can be understood
@@ -442,36 +435,22 @@
Documentation's developer's point of view
-----------------------------------------
-As little hassle as possible.
-
- - minimun barrier to drawing a even small diagram to make
- document more clear, and to new documents
-
-After Step 1 from user's perspective, the computer has *all* the information
-needed for steps 2 and 3, so *no further changes should be required*.
-
- - only explicit link from diagram object to the class it represents is
- obligatory, all other are implicit
-
-For Step 1, it is best to demand explicit links in the UML diagrams.
-
-Steps 2,3:
-
- - implicitly embed diagrams into relevant code documentation, and
- backlink code documentation to design documentation
-
-Javadoc comments should not need to be changed at all.
-
-Goals:
-
- - "feeling" that the arch. doc will be read because
- of the backlinks(!)
-
- - 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, or an error when compiling will be given
-
-
+On the developer side, creating diagrams within the arhictecture documentation
+should be as easy and natural as possibel with As little hassle as possible;
+we want to minimun the barrier of drawing even e small diagram to make
+documentation more clear.
+
+For Step 1, we keep it best to demand explicit links in the UML diagrams. User
+have to define for each object in UML diagram if it will be linked. For example
+giving a full java class name with package or a relative path to architecture
+documentation page. After Step 1 from user's perspective, the computer has
*all*
+the information needed for complete also steps 2 and 3, so *no further changes
+should be required*. For example Javadoc comments should not need to be changed
+at all.
+
+During steps 2 and 3 computer only embeds diagrams into previously linked
+documentation pages and creates backlinks to the original documentation
+page.
Analysis from a hypertext theory point of view
==============================================