[MO-java-dev] Java Doc

[Tim M. <tim...@po...>]

Hmmm - have seen this before at OTI where (when I was there many years ago)
we were required to put a method comment on public methods (and this was all
highly disciplined people) - and generally the method and names of the
paramters were all that was needed. I often wanted to write "Does just as it
says on the tin"!

If not - renaming the method is usually a better fix than writing the doc?

The only type of comment needed might be the range of the paramaters - but
then I think that the tests of a method more reliably document this. And if
you've got tests - why create more work by duplicated them in non-executable
code? Maybe a tool to autogenerate the comments would be an answer for those
who don't have good IDE's. We could just ship a little program with the
source code - DocGenerator.exe (that would be more useful).  Of course -
there is sometimes a policy decision, or workaround that does require
documentation, and in this respect Ted is right. But for the mindless
stuff - docgenerator may be a better answer?


For example -  I have just randomly picked a Java class from the javadoc
that I didn't know anything about "Control". The constructor has:

Control(Control.Type type)
          Constructs a Control with the specified type.

and methods:

Control.Type getType()
          Obtains the control's type.

String toString()
          Obtains a String describing the control type and its current
state.


This isn't very useful is it??? There are lots of examples of this -
although once in a while there is a useful doc e.g. (InputStream)

public abstract int read()
                  throws IOExceptionReads the next byte of data from the
input stream. The value byte is returned as an int in the range 0 to 255. If
no byte is available because the end of the stream has been reached, the
value -1 is returned. This method blocks until input data is available, the
end of the stream is detected, or an exception is thrown.

Anyway - I'll stop now :-)


Tim

-----Original Message-----
From: Shellman, Joel [mailto:Joe...@su...]
Sent: 26 August 2002 18:27
To: tim...@po...
Subject: RE: [MO-java-dev] Volunteer: Ted Husted


> I wouldn't want to see the mock objects project go the way of the SUN
> JavaDoc which is quite frankly useless!!! At the method level the doc
simply
> states everything that the method signature gives - what a waste of
energy.

How ironic. I was just reading Sun's guidelines for writting JavaDoc and
they specifically stated that the JavaDoc should not state what is already
in the method signature.

Joel Shellman


---
Incoming mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.381 / Virus Database: 214 - Release Date: 02/08/2002

---
Outgoing mail is certified Virus Free.
Checked by AVG anti-virus system (http://www.grisoft.com).
Version: 6.0.381 / Virus Database: 214 - Release Date: 02/08/2002