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 |
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 |
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 |
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 |
|
|
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 |
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 |
|
|
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 |
|
|
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 |