Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #21435 > unrolled thread

Javadoc rethinking?

Back to article view | Back to comp.lang.java.programmer

Contents

  Javadoc rethinking? bob smith <bob@coolfone.comze.com> - 2013-01-16 07:38 -0800
    Re: Javadoc rethinking? Arne Vajhøj <arne@vajhoej.dk> - 2013-01-16 11:00 -0500
      Re: Javadoc rethinking? Martin Gregorie <martin@address-in-sig.invalid> - 2013-01-16 20:14 +0000
        Re: Javadoc rethinking? Martin Gregorie <martin@address-in-sig.invalid> - 2013-01-16 22:11 +0000
          Re: Javadoc rethinking? Lew <lewbloch@gmail.com> - 2013-01-16 17:00 -0800
            Re: Javadoc rethinking? Martin Gregorie <martin@address-in-sig.invalid> - 2013-01-17 01:25 +0000
    Re: Javadoc rethinking? Steven Simpson <ss@domain.invalid> - 2013-01-16 18:49 +0000
      Re: Javadoc rethinking? "John B. Matthews" <nospam@nospam.invalid> - 2013-01-17 00:35 -0500
    Re: Javadoc rethinking? Jukka Lahtinen <jtfjdehf@hotmail.com.invalid> - 2013-01-16 21:18 +0200
    Re: Javadoc rethinking? Roedy Green <see_website@mindprod.com.invalid> - 2013-01-16 23:33 -0800

#21435 — Javadoc rethinking?

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.  

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

[toc] | [next] | [standalone]

#21436

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

[toc] | [prev] | [next] | [standalone]

#21446

On Wed, 16 Jan 2013 11:00:58 -0500, Arne Vajhøj wrote:

> 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??
>
Yes, the Javadocs docs say you can put both HTML and images in the doc-
files directory.

The only I have is that the docs say you should not put a <title> section 
in package.html because this causes a conflict with HTML-tidy. 
Fortunately, you can ignore this: running "tidy -m ..." generates a 
<title> section which does not cause any problems with javadocs - at 
least, none that I can see.
  

-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#21449

On Wed, 16 Jan 2013 20:14:50 +0000, Martin Gregorie wrote:

> On Wed, 16 Jan 2013 11:00:58 -0500, Arne Vajhøj wrote:
> 
>> 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??
>>
> Yes, the Javadocs docs say you can put both HTML and images in the doc-
> files directory.
> 
> The only I have is that the docs say you should not put a <title>
> section in package.html because this causes a conflict with HTML-tidy.
> Fortunately, you can ignore this: running "tidy -m ..." generates a
> <title> section which does not cause any problems with javadocs - at
> least, none that I can see.
>
Sorry: that should read:

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


-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#21455

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/technotes/tools/solaris/javadoc.html#packagecomment

-- 
Lew

[toc] | [prev] | [next] | [standalone]

#21462

On Wed, 16 Jan 2013 17:00:45 -0800, Lew wrote:

> 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/technotes/tools/solaris/
javadoc.html#packagecomment

package-info.java is only 'preferred' over package.html: the latter is 
not deprecated and IME is sometimes preferable simply because its pure 
HTML and hence easier to synchronise with other documentation, e.g. 
manpages or in situations when you want to inject HTML <a> tags which 
link to HTML pages or images in the associated doc-files directory. 

The advantage of using package.html rathyer than package-info.java is 
that you can check package.html with HTML-tidy or even (shudder) use some 
WYSIWYG HTML authoring tool or word processor to maintain it. 


-- 
martin@   | Martin Gregorie
gregorie. | Essex, UK
org       |

[toc] | [prev] | [next] | [standalone]

#21444

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

[toc] | [prev] | [next] | [standalone]

#21467

In article <da9js9-9o3.ln1@s.simpson148.btinternet.com>,
 Steven Simpson <ss@domain.invalid> 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>

[toc] | [prev] | [next] | [standalone]

#21445

ram@zedat.fu-berlin.de (Stefan Ram) writes:
> bob smith <bob@coolfone.comze.com> 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

[toc] | [prev] | [next] | [standalone]

#21468

On Wed, 16 Jan 2013 07:38:18 -0800 (PST), bob smith
<bob@coolfone.comze.com> 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 

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.java.programmer

csiph-web