Re: best practices for *application* javadoc
Harold Shand wrote:
I have a web app with somewhat iffy documentation and a plan to correct
that. But in reading up on Javadoc it seems all the tutorials and tips
are aimed at developers of APIs. I fully appreciate the importance of
documenting APIs well, but in the case of a fully-bound, end-user
application those rules seem - at first glance anyway - to be overkill.
For instance, most methods are used in just a few places and if I change
a parameter to one the IDE (Eclipse in this case) will immediately point
out the places that need fixing. These methods will never be used
outside the app or overridden (they're final anyway) so in the case of
an application like this, laborious documentation of method parameters
feels like wasted time.
On the other hand, I do want the code to be reasonably well documented
and believe Javadoc has a role in addition to the regular comments which
are already present. I have a few thoughts (e.g. I'm considering
documenting only the classes and constants plus a few of the less
obvious methods) but would like to know if there's any received wisdom
on the subject first. After all, there are plenty of other apps (web and
otherwise) out there. What do they do? Is Javadoc used at all for Java
code which doesn't expose an API?
Full java docs. Always.
For the future.
Unless you have a crystal ball where you can see that no one in
the next decade or two will ever need to call any of your code.
Arne