/[gzz]/manuscripts/UMLLink/short-paper.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/short-paper.rst

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

revision 1.45 by tjl, Thu May 29 09:27:03 2003 UTC revision 1.46 by tjl, Thu May 29 16:00:36 2003 UTC
# Line 161  diagrams into the classes' javadocs to f Line 161  diagrams into the classes' javadocs to f
161    
162  ..  raw:: latex  ..  raw:: latex
163    
164      \begin{figure*}      \begin{figure*}%
165      \label{example}      \begin{centering}%
     \begin{centering}  
166      \includegraphics[height=9cm]{short-trav-3.gen.eps}\hskip .4cm%      \includegraphics[height=9cm]{short-trav-3.gen.eps}\hskip .4cm%
167      \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%      \includegraphics[height=9cm]{short-trav-1.gen.eps}\hskip .4cm%
168      \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%      \includegraphics[height=9cm]{short-trav-4.gen.eps}\hskip .4cm%
169      \end{centering}      \end{centering}%
170      \caption{Three HTML pages modified by Navidoc.      \caption{Three HTML pages modified by Navidoc.
171      The left and center pages are Javadoc pages into which the UML      \label{example}
172      diagrams have been automatically added by Navidoc at half size.      The left and center pages are Javadocs particular interfaces and
173      The right-hand page is a part of the design documentation for      the right-hand page is a part of the design documentation for
174      those interfaces.      those interfaces, which contains a UML diagram
175      The Javadoc pages are for classes which appear      on which the two interfaces described by the Javadoc pages appear.
     in the UML diagram on the design documentation page.  
176      Reduced copies of this diagram have been added to both Javadoc pages.      Reduced copies of this diagram have been added to both Javadoc pages.
177      The elements in the diagram are active: clicking on the Scrollblock      The elements in the diagrams are active: clicking on the Scrollblock
178      element in any of the diagrams takes the user to the Scrollblock      element in any of the diagrams takes the user to the Scrollblock
179      javadoc page.      javadoc.
180      Traversing      Traversing
181      to the design document works by clicking the heading at the      to the design document works by clicking the heading at the
182      top of the diagram.      top of the diagram.
183      In each version of the diagram, the element corresponding to      In each version of the UML diagram,
184      the currently active node is highlighted both with color      the currently active node is highlighted both with color
185      and a distinctive thick, irregular line to catch the viewer's eye.      and a distinctive thick, irregular line to catch the viewer's eye.
186      }      }%
187      \end{figure*}      \end{figure*}
188    
189  ..  The diagram works as  ..  The diagram works as
# Line 386  when using direct manipulation GUIs to c Line 384  when using direct manipulation GUIs to c
384  Experiences  Experiences
385  ===========  ===========
386    
387  Statistics from our project's WWW server show that diagrams  Statistics from the WWW server of our project show that the
388    UML diagrams
389  have been used to traverse between javadoc and design documentation.  have been used to traverse between javadoc and design documentation.
390  During three months (Jan 03 till end of Mar 03), 9% of all  During three months (Jan 03 till end of Mar 03), 9% of all
391  design documentation page request came by traversing from javadoc to  design documentation page request came by traversing from javadoc to
392  design documentation via diagrams. Further, 11% of all  design documentation via diagrams. Further, 11% of all
393  javadoc visits came from design documentation using imagemapped  javadoc visits came from design documentation using imagemapped
394  diagrams.  diagrams.
   
395  Unfortunately, the referrer logs did not allow us to  Unfortunately, the referrer logs did not allow us to
396  identify the use of UML diagrams for navigation  identify the use of UML diagrams for navigation
397  within javadoc pages or within design documents, because those groups  within javadoc pages or within design documents, because there
398  have other links as well. We expect those number  are other links besides the UML diagrams between those pages.
399  would be even higher.  
400    
401    .. We expect those number would be even higher.
402    
403  .. Anecdotally XXX  .. Anecdotally XXX
404    
# Line 419  would be even higher. Line 419  would be even higher.
419  Conclusion  Conclusion
420  ==========  ==========
421    
422  We have presented a navigational aid, which hypertexturally connects  We have presented a navigational aid which hypertexturally connects
423  two distinct areas of documentation, using human-authored UML diagrams  two distinct areas of documentation using human-authored UML diagrams
424  as spatial menus.  as spatial menus.
425  It is not a new idea to use UML diagrams in documentation  Now, it is not a new idea to use UML diagrams as spatial menus ---
426  navigation. For example, Doxygen [heesch03doxygen]_ automatically  for example, Doxygen [heesch03doxygen]_ automatically
427  generates class  generates class
428  inheritance trees for navigation within the embedded documentation.  inheritance trees for navigation within the embedded documentation.
429  Design documentation has been connected to  Also, there has been
430  program code as well, through textual analysis [maletic03recovering]_.  work on connecting design documentation to code
431    as well, e.g. through textual analysis [maletic03recovering]_.
432  However, automatically generated diagrams and indices often include  However, automatically generated diagrams and indices often include
433  too much irrelevant information; human-made UML diagrams are quite different  too much irrelevant information; human-made UML diagrams are quite different
434  from automatically generated ones since they try to *express* a part of  from automatically generated ones since they try to *express* a meaningful
435    part of
436  the system's semantics.  the system's semantics.
437    What is
438  New in our approach is the use of UML diagrams from the design  new in our approach is the use of human-made UML diagrams from the design
439  documentation and their insertion to the relevant Javadoc or other embedded  documentation as spatial menus
440  documentation pages as spatial menus, allowing traversal between the design  on the relevant Javadoc or other embedded
441  documentation and the Javadoc pages.  documentation pages, allowing traversal between the design
442    documentation and the Javadoc pages as well as giving the user an
443    idea of the context of the current class.
444    
445  .. Of course, generated documentation may give well detailed information  .. Of course, generated documentation may give well detailed information
446     from the current implementation, but the design documentation should     from the current implementation, but the design documentation should

Legend:
Removed from v.1.45  
changed lines
  Added in v.1.46

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