Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Java > Javadoc rethinking?

Reply
Thread Tools

Javadoc rethinking?

 
 
bob smith
Guest
Posts: n/a
 
      01-16-2013
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?
 
Reply With Quote
 
 
 
 
Arne Vajhøj
Guest
Posts: n/a
 
      01-16-2013
On 1/16/2013 10:38 AM, bob smith wrote:
> 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

 
Reply With Quote
 
 
 
 
Stefan Ram
Guest
Posts: n/a
 
      01-16-2013
bob smith <(E-Mail Removed)> writes:
>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.)

 
Reply With Quote
 
Steven Simpson
Guest
Posts: n/a
 
      01-16-2013
On 16/01/13 15:38, bob smith wrote:
> 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>

--
ss at comp dot lancs dot ac dot uk

 
Reply With Quote
 
Jukka Lahtinen
Guest
Posts: n/a
 
      01-16-2013
http://www.velocityreviews.com/forums/(E-Mail Removed)-berlin.de (Stefan Ram) writes:
> bob smith <(E-Mail Removed)> writes:
>>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 |


> (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.

--
Jukka Lahtinen
 
Reply With Quote
 
Lew
Guest
Posts: n/a
 
      01-17-2013
Martin Gregorie wrote:
> "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...packagecomment

--
Lew
 
Reply With Quote
 
John B. Matthews
Guest
Posts: n/a
 
      01-17-2013
In article <(E-Mail Removed)148.btinternet.com>,
Steven Simpson <(E-Mail Removed)> wrote:

> On 16/01/13 15:38, bob smith wrote:
> > 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>

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

--
John B. Matthews
trashgod at gmail dot com
<http://sites.google.com/site/drjohnbmatthews>
 
Reply With Quote
 
Roedy Green
Guest
Posts: n/a
 
      01-17-2013
On Wed, 16 Jan 2013 07:38:18 -0800 (PST), bob smith
<(E-Mail Removed)> wrote, quoted or indirectly quoted someone
who said :

>
>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
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
How to add JavaDoc (Java API) to Eclipse Help system Hannes Heckner Java 5 07-22-2009 01:11 PM
javadoc Linking Classes Bryan R. Meyer Java 3 11-19-2003 09:25 AM
javadoc Taki Java 2 10-30-2003 04:27 PM
javadoc -linkoffline help relaxedrob@optushome.com.au Java 2 09-30-2003 04:14 PM
Standalone Javadoc Editor Linus Nikander Java 0 09-10-2003 11:04 AM



Advertisments