77 |
for several languages |
for several languages |
78 |
[devanbu99chime-andalso-friendly95javadoc-andalso-heesch03doxygen]_. |
[devanbu99chime-andalso-friendly95javadoc-andalso-heesch03doxygen]_. |
79 |
Similarly, requirements tracing --- managing relations |
Similarly, requirements tracing --- managing relations |
80 |
between requirements and design decisions is relatively |
between requirements and design decisions --- is relatively |
81 |
well developed [gotel94reqtracing]_. |
well developed [gotel94reqtracing]_. |
82 |
|
|
83 |
.. Gotel could be a little critical for that context, |
.. Gotel could be a little critical for that context, |
92 |
This can be daunting to a newcomer; consider the javadoc |
This can be daunting to a newcomer; consider the javadoc |
93 |
in Sun's Java2 SDK 1.4.1 |
in Sun's Java2 SDK 1.4.1 |
94 |
for the interface ``java.security.PublicKey``. |
for the interface ``java.security.PublicKey``. |
95 |
While the class is easy to find through the package and class lists |
While the class is easily found through the package and class lists |
96 |
when looking for a class to represent cryptographical public keys, |
when looking for a class representing cryptographical public keys, |
97 |
the javadoc is not terribly useful: there is no information |
the javadoc is not terribly useful: it lacks the information |
98 |
there on how one may create objects that implement this interface. |
there on how to create objects that implement this interface. |
99 |
The only way to find this out is to click on the ``Use`` link |
Currently, the only relevant links are on an accompanying ``Use`` page, |
100 |
which lists all the occurrences of this class as method |
which lists all the occurrences of this class elsewhere in the |
101 |
return values or parameters, without much contextual information |
documentation. |
102 |
about the importance of the methods - the methods for |
Further, those lists lack information about the contextual importance of |
103 |
creating a ``PublicKey`` are listed alongside the methods |
the methods --- the methods for |
104 |
that return a ``PublicKey`` contained in another object.. |
creating a ``PublicKey`` are listed alongside eg. the methods |
105 |
|
that return a ``PublicKey`` contained in another object. |
106 |
|
|
107 |
Far more helpful would be a link to the design |
Far more helpful would be a link to the design |
108 |
documentation, even just a diagram of what the intended |
documentation, even just a diagram showing the intended |
109 |
uses or lifespans of classes implementing this interface |
uses or lifespans of related objects and how one creates the objects. |
|
are and how one creates them. |
|
110 |
These diagrams certainly exist for all properly managed |
These diagrams certainly exist for all properly managed |
111 |
medium-to-large scale software projects --- the problem is getting |
medium-to-large scale software projects --- the problem is getting |
112 |
them to where it matters without having to manually insert |
them to where it matters without having to manually insert |