272 |
- can be useful to link even concept with the class |
- can be useful to link even concept with the class |
273 |
that eventually implemented it. |
that eventually implemented it. |
274 |
|
|
275 |
|
- Packages to either Java packages, or the package design document |
276 |
|
|
277 |
Documentation's reader's point of view |
Documentation's reader's point of view |
278 |
--------------------------------------- |
--------------------------------------- |
279 |
|
|
334 |
we can reduce the size of the diagram in the javadoc by 50%. |
we can reduce the size of the diagram in the javadoc by 50%. |
335 |
|
|
336 |
+ technical note: hovering mouse over diagram will show |
+ technical note: hovering mouse over diagram will show |
337 |
class names even on diminished diagrams |
link target class names even on diminished diagrams |
338 |
|
|
339 |
Advantage over paper: MAJOR: multi-end links easily traversable, |
Advantage over paper: MAJOR: multi-end links easily traversable, |
340 |
structure can be understood |
structure can be understood |
342 |
Documentation's developer's point of view |
Documentation's developer's point of view |
343 |
----------------------------------------- |
----------------------------------------- |
344 |
|
|
345 |
+ HTML/WWW browsers don't support bi-directional links |
As little hassle as possible. |
|
|
|
|
Goals: |
|
|
|
|
|
- small, incremental changes to existing javadoc / other documentation |
|
|
|
|
|
- Low threshold for writing new documentation, diagrams etc. |
|
346 |
|
|
347 |
- minimun barrier to drawing a even small diagram to make |
- minimun barrier to drawing a even small diagram to make |
348 |
document more clear, and to new documents |
document more clear, and to new documents |
349 |
|
|
350 |
- "feeling" that the arch. doc will be read(!) |
After Step 1 from user's perspective, the computer has *all* the information |
351 |
|
needed for steps 2 and 3, so *no further changes should be required*. |
352 |
|
|
353 |
|
For Step 1, it is best to demand explicit links in the UML diagrams. |
354 |
|
|
355 |
- link diagrams' objects to code documentation, which |
Steps 2,3: |
|
they represent |
|
356 |
|
|
357 |
- implicitly embed diagrams into relevant code documentation, and |
- implicitly embed diagrams into relevant code documentation, and |
358 |
backlink code documentation to design documentation |
backlink code documentation to design documentation |
359 |
|
|
360 |
|
Javadoc comments should not need to be changed at all. |
361 |
|
|
362 |
|
Goals: |
363 |
|
|
364 |
|
- "feeling" that the arch. doc will be read(!) |
365 |
|
|
366 |
- if diagrams try to link objects, which don't exist (e.g. removed |
- if diagrams try to link objects, which don't exist (e.g. removed |
367 |
Java class), the linking objects will be specially marked |
Java class), the linking objects will be specially marked |
368 |
e.g. colored red, or an error when compiling will be given |
e.g. colored red, or an error when compiling will be given |
433 |
Implementation |
Implementation |
434 |
============== |
============== |
435 |
|
|
436 |
|
+ HTML/WWW browsers don't support bi-directional links |
437 |
|
|
438 |
Goals: |
Goals: |
439 |
|
|
440 |
- light-weight |
- light-weight |