17 |
should be more general, and we should point out that |
should be more general, and we should point out that |
18 |
this situation is probably not uncommon. |
this situation is probably not uncommon. |
19 |
|
|
|
- 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 |
|
|
|
|
20 |
- why even outdated but well simplified diagram |
- why even outdated but well simplified diagram |
21 |
is better than too detailed, automaticly up-to dated |
is better than too detailed, automaticly up-to dated |
22 |
and reverse engineered diagram. |
and reverse engineered diagram. |
36 |
of cross-hierarchical links and browsin along them still unkown. |
of cross-hierarchical links and browsin along them still unkown. |
37 |
When generating sourcecode, the documentation could be embedded into |
When generating sourcecode, the documentation could be embedded into |
38 |
source as comments. Some user comment didn't like Rose's way of |
source as comments. Some user comment didn't like Rose's way of |
39 |
adding extra comments into generated code <http://c2.com/cgi/wiki?RationalRose> |
adding extra comments into generated code |
40 |
|
<http://c2.com/cgi/wiki?RationalRose> |
41 |
|
|
42 |
Introduction |
Introduction |
43 |
============ |
============ |
44 |
|
|
45 |
UML, the blah, has recently become blah blah |
UML (the Unified Modeling Language), found mainly by Booch, Jacobson and |
46 |
|
Rumbaugh during 1900s to XXX blah blah [#]_, has become *de facto* |
47 |
|
industry-standard language for specifying, visualizing, constructing, |
48 |
|
and documenting the products in software engineering. Recently, various |
49 |
|
approaches have been developed towards unifying software architecture |
50 |
|
design and code. Whether the source code is generated from the UML-based |
51 |
|
architectural model [#]_ or the documentation is reverse engineered from |
52 |
|
the code [#]_. Nowadays UML seem to be taken in CASE tools even almost |
53 |
|
as a visual language, though it's not primarly designed to be a |
54 |
|
programming language. [#]_. |
55 |
|
|
56 |
|
.. [#] XXX booch-jacobson-rumbaugh-uml-user-guide? |
57 |
|
|
58 |
|
.. [#] harrison-barton-raghavachari00uml-to-java |
59 |
|
|
60 |
|
.. [#] pierce-tilley02connecting-documentation-rose |
61 |
|
|
62 |
|
.. [#] booch-jacobson-rumbaugh-uml-user-guide p.15 |
63 |
|
booch-jacobson-rumbaugh-uml-reference-manual p.4 |
64 |
|
|
65 |
|
Against the trend of unifying the architectural documentation and code |
66 |
|
using UML, we tend still to define the details in the source code and |
67 |
|
use UML only for planning and document our software architecture in more |
68 |
|
general level. We keep UML as a common language for intercommunication |
69 |
|
within our software developer team and within project's all stakeholders. |
70 |
|
In this purpose we prefer more well abstracted and comprehensible |
71 |
|
human drawn diagrams than exact spesifications matching source code to |
72 |
|
every detail. |
73 |
|
|
74 |
UML book [booch-jacobson-rumbaugh-uml-used-guide, p.24]:: |
[#]_:: |
75 |
|
|
76 |
"You draw diagrams to visualize a system from different |
"You draw diagrams to visualize a system from different |
77 |
perspectives, so a diagram is a projection into a system. |
perspectives, so a diagram is a projection into a system. |
78 |
For all but the most trivial systems, a diagram represents an elided |
For all but the most trivial systems, a diagram represents an elided |
79 |
view of the elements that make up a system." |
view of the elements that make up a system." |
80 |
|
|
81 |
Recently, various approaches have been developed towards |
.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24 |
|
unifying software architecture design and code (REFS) |
|
82 |
|
|
83 |
* they seem to end up generating either the documentation |
Altough, even if the architectural documentation won't fully match with |
84 |
from the code or the code from the documentation |
details of current implementation, we feel important to enable fast |
85 |
(antont's note about duplication of data problem) |
transitions between them. In this article, we present the tools we |
86 |
|
developed for using UML diagrams as multiple-ended hyperlinks between the |
87 |
[harrison-barton-raghavachari00java-to-uml] |
architectural documents and javadoc generated java source documentation. |
|
[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. |
|
88 |
|
|
89 |
Background |
Background |
90 |
========== |
========== |
138 |
decentralized working places - is especially vulnerable to |
decentralized working places - is especially vulnerable to |
139 |
intercommunication problems |
intercommunication problems |
140 |
|
|
141 |
|
Javadoc |
142 |
|
------- |
143 |
|
|
144 |
|
Javadoc [#]_ is a hypertext documentation tool developed by Sun |
145 |
|
Microsystems and delivered with Sun's Java distribution packages [#]_. |
146 |
|
Javadoc generates detailed and well crosslinked documentation analyzing |
147 |
|
classes and including also comments from java source packages. Besides |
148 |
|
crosslinking, Javadoc creates indexes and archical trees as navigational |
149 |
|
aids for finding individual classes. |
150 |
|
|
151 |
|
.. [#] http://java.sun.com/j2se/javadoc/ |
152 |
|
|
153 |
|
.. [#] Java is a trademark of Sun Microsystems |
154 |
|
|
155 |
|
Sun's distribution of Javadoc tools is proprietary, but there exists |
156 |
|
also free software (licensed unde GPL) alternatives like doc++ [#]_, |
157 |
|
which can create documentation also from sources of other languages |
158 |
|
(e.g. C++). |
159 |
|
|
160 |
|
.. [#] http://docpp.sourceforge.net/ |
161 |
|
|
162 |
UML |
UML |
163 |
--- |
--- |
164 |
|
|
181 |
- co-operating with Rational Soda, Soda is WYSIWYG |
- co-operating with Rational Soda, Soda is WYSIWYG |
182 |
[pierce-tilley02connecting-documentation-rose] |
[pierce-tilley02connecting-documentation-rose] |
183 |
|
|
184 |
|
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
185 |
|
surely ask about that, |
186 |
|
|
187 |
|
PARTIAL RESOLUTION: |
188 |
|
|
189 |
|
- proprietarity (really?) |
190 |
|
- versioning much worse |
191 |
|
(changes in rtf could probably be compared?) |
192 |
|
- users = programmers --> used to editing text and compiling, |
193 |
|
it's the most practical to use the same editor as for coding |
194 |
|
- lack of good, **extensible** tools |
195 |
|
|
196 |
|
|
197 |
|
[gentner-nielsen-anti-mac, p.75] collects arguments/argues |
198 |
|
generally against WYSIWYG. |
199 |
|
|
200 |
|
- a document has a rich semantic structure that is poorly |
201 |
|
captured by its appearance on a sceen or printed page |
202 |
|
- other text representations, such as SGML, distinct the semantic |
203 |
|
structure and rules for converting the text and semantics into |
204 |
|
printablepage |
205 |
|
- WYSIWYG assumes there is only one useful representation of the |
206 |
|
information: that of the final reports |
207 |
|
- WYSIWYG assumes people want paper-style reports (and we already |
208 |
|
live within information flood) |
209 |
|
- blind users exists |
210 |
|
|
211 |
|
- Rational Soda is WYSIWYG, maybe this could be discussed under |
212 |
|
it |
213 |
|
|
214 |
- though, because we are coders, we would prefer UML script |
- though, because we are coders, we would prefer UML script |
215 |
language over menus and dialogs when creating UML objects |
language over menus and dialogs when creating UML objects |
216 |
|
|
266 |
|
|
267 |
- proprietary |
- proprietary |
268 |
|
|
269 |
Dia (drawing, generating code templates) |
Dia (drawing, generating code templates) |
270 |
|
|
271 |
|
- Dia [#]_ a free software (licensed under GPL) diagram creating program |
272 |
|
with direct manipulation user interface. |
273 |
- more a drawing than a design tool |
- more a drawing than a design tool |
274 |
- could be used instead of metapost, but |
- could be used instead of metapost, but |
275 |
direct manipulation problem again |
direct manipulation problem again |
276 |
- open source |
|
277 |
|
.. [#] http://www.lysator.liu.se/~alla/dia/ |
278 |
|
|
279 |
Doxygen |
Doxygen |
280 |
|
|
281 |
|
- Doxygen [#]_ is an another Javadoc-like documentation tool, which |
282 |
|
generates hypertext documentation from source code of good variety |
283 |
|
of different languges. An intresting feature in Doxygen is that |
284 |
|
it generates and embeds UML diagrams representing software's |
285 |
|
class and inheritance hierarchies into class documentation. Also |
286 |
|
the currently viewed class is higlighted in diagrams. Doxygen |
287 |
|
also creates shrinkable treeview for class hierarchy. |
288 |
|
|
289 |
- can generate useless diagrams from the code class hierarchy |
- can generate useless diagrams from the code class hierarchy |
290 |
- should describe somewhere why these are useles... |
- should describe somewhere why these are useles... |
291 |
- uses non open source graphviz |
- uses proprietary GraphViz tool to create diagrams |
292 |
|
|
293 |
|
.. [#] http://www.doxygen.org/ |
294 |
|
|
295 |
MetaPhor, hypertext in soft. devel? [metaphor] |
MetaPhor, hypertext in soft. devel? [metaphor] |
296 |
|
|
310 |
combines all the good parts we need from previous tools without |
combines all the good parts we need from previous tools without |
311 |
reformin dramatically our workin culture.) |
reformin dramatically our workin culture.) |
312 |
|
|
|
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 |
|
|
|
|
313 |
Setting of problem |
Setting of problem |
314 |
================== |
================== |
315 |
|
|
668 |
but very limiting. The system we are using these tools to develop is |
but very limiting. The system we are using these tools to develop is |
669 |
intended for better user interfaces to similar ... |
intended for better user interfaces to similar ... |
670 |
|
|
671 |
|
+ antont's note about duplication of data problem |
672 |
|
|
673 |
- Currently, we only link UML classifiers to Java classes and other documents. Methods |
- Currently, we only link UML classifiers to Java classes and other documents. Methods |
674 |
could also be linked, especially in interaction diagrams. |
could also be linked, especially in interaction diagrams. |
675 |
|
|