/[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.34 by tjl, Wed Jan 22 21:07:44 2003 UTC revision 1.35 by tjl, Wed Jan 22 21:11:28 2003 UTC
# Line 170  In our project, ..., Line 170  In our project, ...,
170  the software engineering documentation  the software engineering documentation
171  is divided into two classes:  is divided into two classes:
172    
 The two types of documentation are complementary.  
   
 +----------------------------------------+----------------------------------------------+  
 |       Design docs                      |           Javadoc                            |  
 +----------------------------------------+----------------------------------------------+  
 |                                        |                                              |  
 | - good overall picture.                |  - easy to find a given class,               |  
 |                                        |    easy to check all methods                 |  
 |                                        |                                              |  
 | - little detail,                       |  - detailed                                  |  
 |                                        |                                              |  
 | - may be slightly outdated at          |  - methods and classes *always* up to        |  
 |   any particular time.                 |    date (generated from source),             |  
 |                                        |    doc comments also usually                 |  
 |                                        |                                              |  
 | - hard to find explanations            |  - no overall picture of classes' roles      |  
 |   for a particular class.              |                                              |  
 |                                        |                                              |  
 | - UML diagrams                         |                                              |  
 |                                        |                                              |  
 | - written and organized by humans      |                                              |  
 |                                        |                                              |  
 +----------------------------------------+----------------------------------------------+  
   
173  Javadoc  Javadoc
174    
175   - fully generated documentation from javadoc comments   - fully generated documentation from javadoc comments
# Line 202  Javadoc Line 178  Javadoc
178     + the javadoc output filestructure follows the     + the javadoc output filestructure follows the
179       hierarchical tree structure of java packages and classes       hierarchical tree structure of java packages and classes
180    
  + hypertext disorientation problem still exists  
   
    Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:  
    Cognitive Mapping and Navigation in a Hypertext Environment.  
    In R. McAleese, & C. Green (Eds.), Hypertext: Theory into  
    Practice (105-125), Oxford: Intellect Limited.  
    (code in JYU-lib: "MK TIE HYPER")  
   
   
181  Architectural docs with UML diagrams:  Architectural docs with UML diagrams:
182    
183    
# Line 236  Architectural docs with UML diagrams: Line 203  Architectural docs with UML diagrams:
203   - Include PEGs: possibly not-yet accepted or not-yet implemented proposals   - Include PEGs: possibly not-yet accepted or not-yet implemented proposals
204     for architectural changes.     for architectural changes.
205    
206    
207    The two types of documentation are complementary, as demonstrated in the following table..
208    
209    +----------------------------------------+----------------------------------------------+
210    |       Design docs                      |           Javadoc                            |
211    +----------------------------------------+----------------------------------------------+
212    |                                        |                                              |
213    | - good overall picture.                |  - easy to find a given class,               |
214    |                                        |    easy to check all methods                 |
215    |                                        |                                              |
216    | - little detail,                       |  - detailed                                  |
217    |                                        |                                              |
218    | - may be slightly outdated at          |  - methods and classes *always* up to        |
219    |   any particular time.                 |    date (generated from source),             |
220    |                                        |    doc comments also usually                 |
221    |                                        |                                              |
222    | - hard to find explanations            |  - no overall picture of classes' roles      |
223    |   for a particular class.              |                                              |
224    |                                        |                                              |
225    | - UML diagrams                         |                                              |
226    |                                        |                                              |
227    | - written and organized by humans      |                                              |
228    |                                        |                                              |
229    +----------------------------------------+----------------------------------------------+
230  "Obvious" question: can we increase the overall value by  "Obvious" question: can we increase the overall value by
231  interconnecting the two?  interconnecting the two?
232    
233    Architectural docs easily left in the dark reaches of the filesystem,
234    not used as often as javadocs.
235    
236     + hypertext disorientation problem still exists
237    
238       Edwards, D., & Hardman, L. (1989). Lost in Hyperspace:
239       Cognitive Mapping and Navigation in a Hypertext Environment.
240       In R. McAleese, & C. Green (Eds.), Hypertext: Theory into
241       Practice (105-125), Oxford: Intellect Limited.
242       (code in JYU-lib: "MK TIE HYPER")
243    
244    
245  Design  Design
246  ======  ======

Legend:
Removed from v.1.34  
changed lines
  Added in v.1.35

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