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 |
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 |
|
|
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 |
====== |
====== |