Javadoc rethinking?

[bob smith]

Am I the only one who thinks that maybe there ought to be some improvementsto the Javadoc process?

I was just looking at a Javadoc for a DatePickerDialog, and it seemed like it was missing something… that something was an image of an example of the dialog. I think that would have been very helpful.

However, Javadocs don't support images, and it is not necessarily good for the crucial documentation to be mingled with the code.

Does anyone else think the Javadoc idea could perhaps use some rethinking?

 

[Arne Vajhøj]

Am I the only one who thinks that maybe there ought to be some
improvements to the Javadoc process?

I was just looking at a Javadoc for a DatePickerDialog, and it seemed
like it was missing something… that something was an image of an
example of the dialog. I think that would have been very helpful.

However, Javadocs don't support images, and it is not necessarily
good for the crucial documentation to be mingled with the code.

JavaDoc support HTML tags and I would assume they support IMG tag??

Arne

 

[Stefan Ram]

However, Javadocs don't support images,

Writing an image of a DatePickerDialog in a JavaDoc-
compatible way only did cost me about 7 minutes.

..--------------------------------------.
| -- |
| |\_| perjantaina 10, kesäkuuta |
| '__' 2011 |
| |
| .-------. .-------. .-------. |
| | + | | + | | + | |
| |-------| |-------| |-------| |
| | 10 | |kuuta | | 2011 | |
| |-------| |-------| |-------| |
| | - | | - | | - | |
| '-------' '-------' '-------' |
| |
|--------------------------------------|
| .--------------. .----------------. |
| | Aseta | | Peruuta | |
| '--------------' '----------------' |
'--------------------------------------'

One could even imagine an implementation of Swing for text
terminals, where the DatePickerDialog would look like that
literally.

(I do not know the language of the dialog as used above.)

 

[Steven Simpson]

However, Javadocs don't support images, and it is not necessarily good for the crucial documentation to be mingled with the code.

<http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed>

 

[Jukka Lahtinen]

Writing an image of a DatePickerDialog in a JavaDoc-
compatible way only did cost me about 7 minutes.
.--------------------------------------.
| -- |
| |\_| perjantaina 10, kesäkuuta |
| '__' 2011 |

(I do not know the language of the dialog as used above.)

It's Finnish. (Friday, 10th of June)
Funny that you happened to use it without even recognizing the language.

 

[Lew]

"The only niggle I have is that the Javadocs docs say you should not put
a <title> section in package.html because this causes a conflict with
HTML-tidy."

I thought we were supposed to use package-info.java anyway, not package.html.
http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#packagecomment

 

[John B. Matthews]

<http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#unprocessed>

As a concrete example, the images accompanying GridLayout

<http://docs.oracle.com/javase/7/docs/api/java/awt/GridLayout.html>

may be found among the doc-files of the awt package:

$ ls -1 java/awt/doc-files/GridLayout-*
java/awt/doc-files/GridLayout-1.gif
java/awt/doc-files/GridLayout-2.gif

 

[Roedy Green]

I was just looking at a Javadoc for a DatePickerDialog, and it seemed like =
it was missing something=85 that something was an image of an example of t=
he dialog. I think that would have been very helpful.

AMEN! I have often wanted to illustrate layouts too.

Another feature I would like is commentary on @see to explain why that
other reference might be germane. Or how it differs from this method.

If you start inserting entities, the Javadoc quickly becomes
unreadable to the programmer. The IDE should render it or there should
be some way to write it without entities. Perhaps we should presume
UTF-8 for all Java source.
--
Roedy Green Canadian Mind Products http://mindprod.com
The first 90% of the code accounts for the first 90% of the development time.
The remaining 10% of the code accounts for the other 90% of the development
time.
~ Tom Cargill Ninety-ninety Law