[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/umllink.rst
From: |
Asko Soukka |
Subject: |
[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/umllink.rst |
Date: |
Tue, 28 Jan 2003 09:21:39 -0500 |
CVSROOT: /cvsroot/gzz
Module name: manuscripts
Changes by: Asko Soukka <address@hidden> 03/01/28 09:21:39
Modified files:
. : gzigzag.bib
UMLLink : umllink.rst
Log message:
small progress
CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.49&tr2=1.50&r1=text&r2=text
Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.49
manuscripts/UMLLink/umllink.rst:1.50
--- manuscripts/UMLLink/umllink.rst:1.49 Mon Jan 27 09:19:38 2003
+++ manuscripts/UMLLink/umllink.rst Tue Jan 28 09:21:39 2003
@@ -2,7 +2,7 @@
A free software toolchain for bidirectional linking between UML diagrams and
Javadoc
====================================================================================
-:Stamp: $Id: umllink.rst,v 1.49 2003/01/27 14:19:38 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.50 2003/01/28 14:21:39 humppake Exp $
Issues
======
@@ -17,35 +17,6 @@
should be more general, and we should point out that
this situation is probably not uncommon.
-- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
- surely ask about that,
-
- PARTIAL RESOLUTION:
-
- - proprietarity (really?)
- - versioning much worse (changes in rtf could probably be compared?)
- - users = programmers --> used to editing text and compiling,
- it's the most practical to use the same editor as for coding
- - lack of good, **extensible** tools
-
-
- [gentner-nielsen-anti-mac, p.75] collects arguments/argues
- generally against WYSIWYG.
-
- - a document has a rich semantic structure that is poorly
- captured by its appearance on a sceen or printed page
- - other text representations, such as SGML, distinct the semantic
- structure and rules for converting the text and semantics into
- printablepage
- - WYSIWYG assumes there is only one useful representation of the
- information: that of the final reports
- - WYSIWYG assumes people want paper-style reports (and we already
- live within information flood)
- - blind users exists
-
- - Rational Soda is WYSIWYG, maybe this could be discussed under
- it
-
- why even outdated but well simplified diagram
is better than too detailed, automaticly up-to dated
and reverse engineered diagram.
@@ -65,34 +36,55 @@
of cross-hierarchical links and browsin along them still unkown.
When generating sourcecode, the documentation could be embedded into
source as comments. Some user comment didn't like Rose's way of
- adding extra comments into generated code
<http://c2.com/cgi/wiki?RationalRose>
+ adding extra comments into generated code
+ <http://c2.com/cgi/wiki?RationalRose>
Introduction
============
-UML, the blah, has recently become blah blah
+UML (the Unified Modeling Language), found mainly by Booch, Jacobson and
+Rumbaugh during 1900s to XXX blah blah [#]_, has become *de facto*
+industry-standard language for specifying, visualizing, constructing,
+and documenting the products in software engineering. Recently, various
+approaches have been developed towards unifying software architecture
+design and code. Whether the source code is generated from the UML-based
+architectural model [#]_ or the documentation is reverse engineered from
+the code [#]_. Nowadays UML seem to be taken in CASE tools even almost
+as a visual language, though it's not primarly designed to be a
+programming language. [#]_.
+
+.. [#] XXX booch-jacobson-rumbaugh-uml-user-guide?
+
+.. [#] harrison-barton-raghavachari00uml-to-java
+
+.. [#] pierce-tilley02connecting-documentation-rose
+
+.. [#] booch-jacobson-rumbaugh-uml-user-guide p.15
+ booch-jacobson-rumbaugh-uml-reference-manual p.4
+
+Against the trend of unifying the architectural documentation and code
+using UML, we tend still to define the details in the source code and
+use UML only for planning and document our software architecture in more
+general level. We keep UML as a common language for intercommunication
+within our software developer team and within project's all stakeholders.
+In this purpose we prefer more well abstracted and comprehensible
+human drawn diagrams than exact spesifications matching source code to
+every detail.
-UML book [booch-jacobson-rumbaugh-uml-used-guide, p.24]::
+[#]_::
"You draw diagrams to visualize a system from different
perspectives, so a diagram is a projection into a system.
For all but the most trivial systems, a diagram represents an elided
- view of the elements that make up a system."
+ view of the elements that make up a system."
-Recently, various approaches have been developed towards
-unifying software architecture design and code (REFS)
+.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
- * they seem to end up generating either the documentation
- from the code or the code from the documentation
- (antont's note about duplication of data problem)
-
- [harrison-barton-raghavachari00java-to-uml]
- [pierce-tilley02connecting-documentation-rose]
-
-In this article, we present the tools we developed
-for using UML diagrams as multiple-ended hyperlinks
-between the architectural documents and javadoc generated
-java source documentation.
+Altough, even if the architectural documentation won't fully match with
+details of current implementation, we feel important to enable fast
+transitions between them. In this article, we present the tools we
+developed for using UML diagrams as multiple-ended hyperlinks between the
+architectural documents and javadoc generated java source documentation.
Background
==========
@@ -146,6 +138,27 @@
decentralized working places - is especially vulnerable to
intercommunication problems
+Javadoc
+-------
+
+Javadoc [#]_ is a hypertext documentation tool developed by Sun
+Microsystems and delivered with Sun's Java distribution packages [#]_.
+Javadoc generates detailed and well crosslinked documentation analyzing
+classes and including also comments from java source packages. Besides
+crosslinking, Javadoc creates indexes and archical trees as navigational
+aids for finding individual classes.
+
+.. [#] http://java.sun.com/j2se/javadoc/
+
+.. [#] Java is a trademark of Sun Microsystems
+
+Sun's distribution of Javadoc tools is proprietary, but there exists
+also free software (licensed unde GPL) alternatives like doc++ [#]_,
+which can create documentation also from sources of other languages
+(e.g. C++).
+
+.. [#] http://docpp.sourceforge.net/
+
UML
---
@@ -168,6 +181,36 @@
- co-operating with Rational Soda, Soda is WYSIWYG
[pierce-tilley02connecting-documentation-rose]
+ - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
+ surely ask about that,
+
+ PARTIAL RESOLUTION:
+
+ - proprietarity (really?)
+ - versioning much worse
+ (changes in rtf could probably be compared?)
+ - users = programmers --> used to editing text and compiling,
+ it's the most practical to use the same editor as for coding
+ - lack of good, **extensible** tools
+
+
+ [gentner-nielsen-anti-mac, p.75] collects arguments/argues
+ generally against WYSIWYG.
+
+ - a document has a rich semantic structure that is poorly
+ captured by its appearance on a sceen or printed page
+ - other text representations, such as SGML, distinct the semantic
+ structure and rules for converting the text and semantics into
+ printablepage
+ - WYSIWYG assumes there is only one useful representation of the
+ information: that of the final reports
+ - WYSIWYG assumes people want paper-style reports (and we already
+ live within information flood)
+ - blind users exists
+
+ - Rational Soda is WYSIWYG, maybe this could be discussed under
+ it
+
- though, because we are coders, we would prefer UML script
language over menus and dialogs when creating UML objects
@@ -223,19 +266,31 @@
- proprietary
-Dia (drawing, generating code templates)
+Dia (drawing, generating code templates)
+ - Dia [#]_ a free software (licensed under GPL) diagram creating program
+ with direct manipulation user interface.
- more a drawing than a design tool
- could be used instead of metapost, but
direct manipulation problem again
- - open source
+
+.. [#] http://www.lysator.liu.se/~alla/dia/
Doxygen
+ - Doxygen [#]_ is an another Javadoc-like documentation tool, which
+ generates hypertext documentation from source code of good variety
+ of different languges. An intresting feature in Doxygen is that
+ it generates and embeds UML diagrams representing software's
+ class and inheritance hierarchies into class documentation. Also
+ the currently viewed class is higlighted in diagrams. Doxygen
+ also creates shrinkable treeview for class hierarchy.
+
- can generate useless diagrams from the code class hierarchy
- should describe somewhere why these are useles...
- - uses non open source graphviz
+ - uses proprietary GraphViz tool to create diagrams
+.. [#] http://www.doxygen.org/
MetaPhor, hypertext in soft. devel? [metaphor]
@@ -255,15 +310,6 @@
combines all the good parts we need from previous tools without
reformin dramatically our workin culture.)
-Javadoc
--------
-
-Javadoc, the hypertext documentation tool that comes with
-Java (trademark of Sun Microsystems, Javadoc is distributed only
-as part of Java, non-free), is ...
-
-doc++ a free software alternative for javadoc
-
Setting of problem
==================
@@ -621,6 +667,8 @@
presentation/UI layer of a hypertext system is useful and standard
but very limiting. The system we are using these tools to develop is
intended for better user interfaces to similar ...
+
+ + antont's note about duplication of data problem
- Currently, we only link UML classifiers to Java classes and other documents.
Methods
could also be linked, especially in interaction diagrams.
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.11 manuscripts/gzigzag.bib:1.12
--- manuscripts/gzigzag.bib:1.11 Mon Jan 27 09:19:38 2003
+++ manuscripts/gzigzag.bib Tue Jan 28 09:21:39 2003
@@ -2730,7 +2730,7 @@
publisher = {Reading, MA: Addison-Wesley},
}
address@hidden,
address@hidden,
author = {William Harrison , Charles Barton , Mukund Raghavachari},
title = {Mapping UML designs to Java},
booktitle = {ACM SIGPLAN Notices},