/[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.11 by tjl, Tue May 20 18:04:41 2003 UTC revision 1.12 by tjl, Tue May 20 19:18:25 2003 UTC
# Line 35  Bridging Javadoc and design documentatio Line 35  Bridging Javadoc and design documentatio
35     Requirements traceability research     Requirements traceability research
36     http://www.sei.cmu.edu/str/descriptions/reqtracing_body.html     http://www.sei.cmu.edu/str/descriptions/reqtracing_body.html
37     http://www.cis.ksu.edu/~hankley/d841/Fa99/chap2.htm     http://www.cis.ksu.edu/~hankley/d841/Fa99/chap2.htm
38    
39     http://www.computer.org/proceedings/apsec/0915/09150206abs.htm?SMSESSION=NO     http://www.computer.org/proceedings/apsec/0915/09150206abs.htm?SMSESSION=NO
40    
41     http://www.computer.org/software/so1994/s4104abs.htm     http://www.computer.org/software/so1994/s4104abs.htm
# Line 52  Introduction Line 53  Introduction
53    
54  Software projects manage a large base of evolving documentation, whose  Software projects manage a large base of evolving documentation, whose
55  parts are  parts are
56  inter-related on many levels. Design documentation shows  inter-related on many levels.
57    Design documentation shows
58  architectural views on a more general level, while  architectural views on a more general level, while
59  the source code (in e.g. Java and nowadays often also C++)  the source code (in e.g. Java and nowadays often also C++)
60  contains  contains
# Line 67  from the embedded documentation is essen Line 69  from the embedded documentation is essen
69  a solved problem  a solved problem
70  for several languages  for several languages
71  [friendly95javadoc-andalso-heesch03doxygen-andalso-devanbu99chime]_.  [friendly95javadoc-andalso-heesch03doxygen-andalso-devanbu99chime]_.
72    Similarly, requirements tracing --- managing relations
73    between requirements and design decisions is relatively
74    well developed [XXX]_.
75    
76    What is often missing is the connections between
77    the design documentation and the embedded documentation.
78    This can be daunting to a newcomer; consider the javadoc
79    for the interface ``java.security.PublicKey`` in Sun's
80    Java2 SDK 1.4.1 at
81    ``http://java.sun.com/j2se/1.4.1/docs/api/java/security/PublicKey.html``.
82    XXXREF
83    While the class is easy to find through the package and class lists
84    when looking for a class to represent cryptographical public keys,
85    the javadoc is not terribly useful: there is no information
86    there on how one may create objects that implement this interface.
87    The only way to find this out is to click on the ``Use`` link
88    which lists all the occurrences of this class as method
89    return values or parameters.
90    However, what would really help would be a link to the design
91    documentation, even just a UML diagram of what the intended
92    uses or lifespans of classes implementing this interface
93    are and how one creates them.
94    
95    In this article, we discuss Navidoc: a system that, given design
96    documentation with marked-up UML diagrams, inserts the UML
97    diagrams into the classes' javadocs to function as spatial menus.
98    
99    
100    
101  ..  There exist plenty of documentation tools to generate well navigable  ..  There exist plenty of documentation tools to generate well navigable
# Line 89  for several languages Line 118  for several languages
118     quostions alike. Check at first the keywords given by referees     quostions alike. Check at first the keywords given by referees
119     of UMLLink article.     of UMLLink article.
120    
121  Connecting the distinct areas is essential because it could help new  ..  Connecting the distinct areas is essential because it could help new
122  developers in getting productive and supports development processes      developers in getting productive and supports development processes
123  where both design and implementation change continuously.      where both design and implementation change continuously.
124  Our solution to link distinct software development documentations      Our solution to link distinct software development documentations
125  together is to base it on UML diagrams which are drawn on design      together is to base it on UML diagrams which are drawn on design
126  documentation to abstract the system under development. We believe      documentation to abstract the system under development. We believe
127  that advantages of using UML diagrams as navigational aids clearly beat      that advantages of using UML diagrams as navigational aids clearly beat
128  the minor additional work that is needed.      the minor additional work that is needed.
129    
130  .. It could be that UML diagrams won't be optimal for navigation of hypertext and  .. It could be that UML diagrams won't be optimal for navigation of hypertext and
131     they won't cover the whole documentation.     they won't cover the whole documentation.
# Line 230  Our approach is different from most tool Line 259  Our approach is different from most tool
259  which rely more on automatically generated links [XXX],  which rely more on automatically generated links [XXX],
260  or inserting connections to the source code [devanbu99chime]_.  or inserting connections to the source code [devanbu99chime]_.
261    
   
262  .. - future  .. - future
263      * fenfire      * fenfire
264    

Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12

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