/[gzz]/manuscripts/UMLLink/article.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/article.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by humppake, Tue Feb 11 19:06:53 2003 UTC revision 1.6 by tuukkah, Wed Feb 12 07:51:41 2003 UTC
# Line 1  Line 1 
1  ====================================================================================  ====================================================================================
2  A free software toolchain for bidirectional linking between UML diagrams and Javadoc  A Free Software toolchain for bidirectional linking between UML diagrams and Javadoc
3  ====================================================================================  ====================================================================================
4    
5    Alternative title: "Bridging Javadoc to design documentation via UML diagrams"?
6    
7  :Stamp: $Id$  :Stamp: $Id$
8    
9  Points for HT people  Points for HT people
# Line 68  technical architecture: Line 70  technical architecture:
70         all documents         all documents
71       * result still browsable in WWW       * result still browsable in WWW
72   * tjl: "quick but elegant hack" - small, useful, free tool   * tjl: "quick but elegant hack" - small, useful, free tool
73   * UML is a *language* - allows concise expression in textual form   * UML is a *language* - allows concise expression
74            * in textual form with our description language
75    
76  navigation:  navigation:
77   * bidirectional   * bidirectional
# Line 104  Conceptual model (for HT people!) Line 107  Conceptual model (for HT people!)
107  * UML diagrams: distinct context for Java classes and packages and relevant  * UML diagrams: distinct context for Java classes and packages and relevant
108    architectural documentation; spatial menu; also node (XXX multi-ended nexus    architectural documentation; spatial menu; also node (XXX multi-ended nexus
109    links)    links)
110            * generated by our UML tool from our UML diagram description language
111    
112  * Cross-reference by Javadoc: cheap cross-link  * Cross-reference by Javadoc: cheap cross-link
113  * Cross-link from javadoc comments: simple hyperlink  * Cross-link from javadoc comments: simple hyperlink
# Line 111  Conceptual model (for HT people!) Line 115  Conceptual model (for HT people!)
115    (poorly implemented as WWW)    (poorly implemented as WWW)
116    
117  * Links in UML diagrams: context navigation links  * Links in UML diagrams: context navigation links
118            * generated by our UML link tool without any extra information
119    
120  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
121    
122    
123  Implementation  Implementation
124  ==============  ==============
125    
126  Eventually, we found no Free Software [XXX] alternatives, which would  Eventually, we found no Free Software [XXX] tools which would
127  have fulfilled our needs. Therefore we decide to proceed with our own  fulfill our needs. Therefore, we decided to proceed with our own
128  implementation. There were several goals to be achieved. The tool had  implementation. There were several goals to be achieved. The tool had
129  to:  to:
130    
131  - be tidy and light weight  - be tidy and light-weight
132    
133  - be built on existing Free Software tools  - be built on existing Free Software tools
134    and be a part of Free Software toolchain    and be a part of Free Software toolchain
135    
136  - generate output easily editable by others (from the source)  - support easy re-editing (from the source)
137    
138  - provide a plugin interface for different documentation tools  - provide a plugin interface for different documentation tools
139    
140    
141  Up to this article all steps beside the last one are implemented. The  Up to this article all steps except the last one are implemented. The
142  existing tools we selected on the base of our documentation tool are:  existing tools we selected as the basis for our documentation tool are:
143  Javadoc [XXX], Docutils [XXX], and our own language based UML diagram  Javadoc [XXX], Docutils [XXX], and our own UML diagram description
144  tool. The UML tools also uses several Free Software utilies to convert  tool. The UML tools also use several free utilies to convert
145  the lexical UML description into final PNG (*Portable Network  the lexical UML description into final *Portable Network
146  Graphics*) diagram files. Such utilies are mpost [XXX] (*MetaPost*),  Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost),
147  pstopnm [XXX] (*PostScript to Portable anymap*), pnmscale [XXX]  which implements a language for picture drawing, and Netpbm image file
148  (*Portable anymap scaling utility*) and pnmtopng (*Portable anymap to  manipulation toolkit. Besides Javadoc, all tools used are Free
 Portable Network Graphics*). Besides Javadoc, all tools used are Free  
149  Software.  Software.
150    
151    
152  ??After the plugin interface is created the documentation  ??After the plugin interface is created, the documentation
153  linking utility could also be used with other HTML documentation  linking utility could also be used with other HTML documentation
154  generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it?  generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it?
155    
156  it is also    it is also  
157    
158    The javadoc format is the standard way to include documentation in Java
159  Because Javadoc have provided good enough fully generated and up-to-dated detailed documentation for our use, we had no reason to abandon it.  source code. Generating the WWW pages is not a complicated process, and at the
160    moment GNU Classpath Tools is developing a Free Software implementation called
161    gjdoc. As Javadoc has provided good enough fully generated and up-to-date
162    detailed documentation for our use, we have had no reason to abandon it yet.
163    
164  On the  On the
165    
166  Although our UML language was already implemented before the linking  Although our UML language was already implemented before the linking
167  tool, which finally created the bi-directional linking between  tool, which finally created the bi-directional linking between
168  documentations, we discuss shortly about why we ended to create a  documentations, we discuss shortly how we arrived at creating a
169  language instead of using a diagram drawing tool with direct  language instead of using a diagram drawing tool with direct
170  manipulation GUI.  manipulation GUI.
171    
# Line 169  reST's filosophy Line 177  reST's filosophy
177  - indentation for blocks  - indentation for blocks
178  - robust for erros  - robust for erros
179  - "natural" to write  - "natural" to write
180  - "ASCII layout" (our UML-language is an exception, which is discussed later)  - "ASCII layout" (our language for UML is an exception, which is discussed
181      later)
182    
183  Why UML-language  Why UML description language
184    
185   - Doxygen can generate useless diagrams from the code class hierarchy   - Doxygen can generate useless diagrams from the code class hierarchy
186     should describe somewhere why these are useles...       * should describe somewhere why these are useles...
187     uses proprietary GraphViz tool to create diagrams       * uses proprietary GraphViz tool to create diagrams
188    
189    
190   - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will   - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
# Line 208  Why UML-language Line 217  Why UML-language
217      - Rational Soda is WYSIWYG, maybe this could be discussed under      - Rational Soda is WYSIWYG, maybe this could be discussed under
218        it        it
219    
220   - though, because we are coders, we would prefer UML script   - though, because we are coders, we would prefer UML description
221     language over menus and dialogs when creating UML objects     language over menus and dialogs when creating UML diagrams
222    
223     + we need a ref. of criticism of direct manipulation!     + we need a ref. of criticism of direct manipulation!
224    
# Line 264  Why UML-language Line 273  Why UML-language
273    
274  - not strictly necessary; could have used another editor  - not strictly necessary; could have used another editor
275    
276  - minimum barrier to make a diagram (well, at first have to learn our UML-script)  - minimum barrier to make a diagram (well, at first have to learn our
277            description language)
278    
279  - direct manipulation when building / editing structure of diagrams clumsy  - direct manipulation when building / editing structure of diagrams clumsy
280    
281       - users are programmers --> a simple programming language is better than d.m.       - users are programmers --> a language is better than d.m.
282    
283        + elements are easy to create by script language        + elements are easily described
284    
285        + graphical placing could need an GUI        + graphical placing would need an GUI
286    
287  - diagrams in the same reST source as the architecture document  - diagrams in the same reST source as the architecture document
288    
# Line 283  Why UML-language Line 293  Why UML-language
293         interactively editable.         interactively editable.
294    
295  - Dia could be used instead of metapost, but  - Dia could be used instead of metapost, but
   direct manipulation problem again  
296      direct manipulation problem again

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26