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

Diff of /manuscripts/UMLLink/umllink.rst

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

revision 1.49 by humppake, Mon Jan 27 14:19:38 2003 UTC revision 1.50 by humppake, Tue Jan 28 14:21:39 2003 UTC
# Line 17  Issues Line 17  Issues
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.
# Line 65  Issues Line 36  Issues
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  ==========  ==========
# Line 146  Software development processes Line 138  Software development processes
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    
# Line 168  Rational Rose Line 181  Rational Rose
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    
# Line 223  Rational Rose Line 266  Rational Rose
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    
# Line 255  MetaPhor, hypertext in soft. devel? [met Line 310  MetaPhor, hypertext in soft. devel? [met
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    
# Line 622  Conclusion Line 668  Conclusion
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    

Legend:
Removed from v.1.49  
changed lines
  Added in v.1.50

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