1 |
==================================================================================== |
========================================================= |
2 |
A Free Software toolchain for bidirectional linking between UML diagrams and Javadoc |
Bridging Javadoc to design documentation via UML diagrams |
3 |
==================================================================================== |
========================================================= |
4 |
|
|
5 |
Alternative title: "Bridging Javadoc to design documentation via UML diagrams"? |
.. Alternative title: "Free Software toolchain for bidirectional |
6 |
|
linking between UML diagrams and Javadoc" |
7 |
|
|
8 |
:Stamp: $Id$ |
.. :Stamp: $Id$ |
9 |
|
|
10 |
Points for HT people |
.. Points for HT people |
11 |
==================== |
==================== |
12 |
|
|
13 |
from HT03 "Call for Papers: Topics for submissions": |
from HT03 "Call for Papers: Topics for submissions": |
14 |
* Hypertext and hypermedia construction |
* Hypertext and hypermedia construction |
15 |
* Link authoring |
* Link authoring |
16 |
* Link maintenance |
* Link maintenance |
62 |
* Interactive games and entertainment |
* Interactive games and entertainment |
63 |
* Museums and archives |
* Museums and archives |
64 |
|
|
65 |
Our work in relation to those: |
.. Our work in relation to those: |
66 |
|
|
67 |
technical architecture: |
technical architecture: |
68 |
* open document base (html) allows: |
* open document base (html) allows: |
69 |
* incorporation of several sources via their own tools (javadoc, rst) |
* incorporation of several sources via their own tools (javadoc, rst) |
70 |
* unified and bidirectional navigation via after-treatment of |
* unified and bidirectional navigation via after-treatment of |
71 |
all documents |
all documents |
72 |
* result still browsable in WWW |
* result still browsable in WWW |
73 |
* tjl: "quick but elegant hack" - small, useful, free tool |
* tjl: "quick but elegant hack" - small, useful, free tool |
74 |
* UML is a *language* - allows concise expression |
* UML is a *language* - allows concise expression |
75 |
* in textual form with our description language |
* in textual form with our description language |
76 |
|
|
77 |
navigation: |
.. navigation: |
78 |
* bidirectional |
* bidirectional |
79 |
* several context views (different UML diagrams), multimenu |
* several context views (different UML diagrams), multimenu |
80 |
* spatial navigation (within the diagram) |
* spatial navigation (within the diagram) |
81 |
|
|
82 |
authoring: |
.. authoring: |
83 |
* creating a diagram creates a new, meaningful browsable context and automatic |
* creating a diagram creates a new, meaningful browsable context and automatic |
84 |
links |
links |
85 |
* works with other www generation tools |
* works with other www generation tools |
86 |
* system is used for communication, thus hypertext documentation is generated |
* system is used for communication, thus hypertext documentation is generated |
87 |
along communication |
along communication |
88 |
|
|
89 |
applications: |
.. applications: |
90 |
* workflow management (?): different phases brought together (PEGs, UMLs, |
* workflow management (?): different phases brought together (PEGs, UMLs, |
91 |
Javadoc) |
Javadoc) |
92 |
* easy to document: any rst can contain UML (what about explicitly in |
* easy to document: any rst can contain UML (what about explicitly in |
93 |
Javadoc?) |
Javadoc?) |
94 |
|
|
95 |
Conceptual model (for HT people!) |
.. Conceptual model (for HT people!) |
96 |
================================= |
================================= |
97 |
|
|
98 |
* Java class: node |
* Java class: node |
99 |
* Java package: hierarchical classification of nodes, also node |
* Java package: hierarchical classification of nodes, also node |
100 |
|
|
101 |
* Documentation: the hypertext universe |
* Documentation: the hypertext universe |
102 |
* the two distinct pieces of documentation: originally no cross-links |
* the two distinct pieces of documentation: originally no cross-links |
103 |
* source code documentation as javadoc-format comments; translated to |
* source code documentation as javadoc-format comments; translated to |
104 |
HTML pages by Sun's Javadoc tool |
HTML pages by Sun's Javadoc tool |
105 |
* architectural documentation (and PEGs) which may contain UML diagrams |
* architectural documentation (and PEGs) which may contain UML diagrams |
106 |
as rst-format files; translated to documentation nodes |
as rst-format files; translated to documentation nodes |
107 |
|
|
108 |
* UML diagrams: distinct context for Java classes and packages and relevant |
* UML diagrams: distinct context for Java classes and packages and relevant |
109 |
architectural documentation; spatial menu; also node (XXX multi-ended nexus |
architectural documentation; spatial menu; also node (XXX multi-ended nexus |
110 |
links) |
links) |
111 |
|
|
112 |
* generated by our UML tool from our UML diagram description language |
* generated by our UML tool from our UML diagram description language |
113 |
|
|
114 |
* Cross-reference by Javadoc: cheap cross-link |
* Cross-reference by Javadoc: cheap cross-link |
115 |
* Cross-link from javadoc comments: simple hyperlink |
* Cross-link from javadoc comments: simple hyperlink |
116 |
* Indexes by Javadoc: hierarchy navigation tool |
* Indexes by Javadoc: hierarchy navigation tool |
117 |
(poorly implemented as WWW) |
(poorly implemented as WWW) |
118 |
|
|
119 |
* Links in UML diagrams: context navigation links |
* Links in UML diagrams: context navigation links |
120 |
* generated by our UML link tool without any extra information |
* generated by our UML link tool without any extra information |
121 |
|
|
122 |
* (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...) |
* (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...) |
123 |
|
|
124 |
|
|
125 |
Diagrams |
.. Diagrams |
126 |
======== |
======== |
127 |
|
|
128 |
Introduction |
Introduction |
129 |
============ |
============ |
221 |
our own UML diagram description tool. Further, the UML tool uses |
our own UML diagram description tool. Further, the UML tool uses |
222 |
several free utilies to convert each lexical UML description into |
several free utilies to convert each lexical UML description into |
223 |
final *Portable Network Graphics* (PNG) diagram files. Such utilies |
final *Portable Network Graphics* (PNG) diagram files. Such utilies |
224 |
are *MetaPost* [hobby89metapost]_ (mpost), which implements a language for picture |
are *MetaPost* [hobby89metapost]_ (mpost), which implements a language |
225 |
drawing, and Netpbm image file manipulation toolkit. Besides Javadoc, |
for picture drawing, and Netpbm image file manipulation |
226 |
all tools used are Free Software. |
toolkit. Besides Javadoc, all tools used are Free Software. The |
227 |
|
current linking utility is implemented to support Javadoc, but after |
228 |
??After the plugin interface is created, the documentation |
the plugin interface is ready, switching Javadoc to any free |
229 |
linking utility could also be used with other HTML documentation |
alternative or using them as parallel should be possible with only |
230 |
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? |
minor plugin programming. |
231 |
|
|
232 |
it is also |
it is also |
233 |
|
|