Groups > comp.lang.java.programmer > #21462

Re: Javadoc rethinking?

Path	csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!us.feeder.erje.net!feeder.erje.net!eu.feeder.erje.net!usenet.ukfsn.org!not-for-mail
From	Martin Gregorie <martin@address-in-sig.invalid>
Newsgroups	comp.lang.java.programmer
Subject	Re: Javadoc rethinking?
Date	Thu, 17 Jan 2013 01:25:35 +0000 (UTC)
Organization	UK Free Software Network
Lines	27
Message-ID	<kd7juf$alo$1@localhost.localdomain> (permalink)
References	<3b10d0bb-0307-4365-b762-d619fd3c608b@googlegroups.com> <50f6cebb$0$285$14726298@news.sunsite.dk> <kd71nq$5p4$1@localhost.localdomain> <kd78ja$7cm$2@localhost.localdomain> <98bee018-641f-4f45-a7c9-31a03842733d@googlegroups.com>
NNTP-Posting-Host	84.45.235.129
Mime-Version	1.0
Content-Type	text/plain; charset=UTF-8
Content-Transfer-Encoding	8bit
X-Trace	localhost.localdomain 1358385935 10936 84.45.235.129 (17 Jan 2013 01:25:35 GMT)
X-Complaints-To	usenet@localhost.localdomain
NNTP-Posting-Date	Thu, 17 Jan 2013 01:25:35 +0000 (UTC)
User-Agent	Pan/0.139 (Sexual Chocolate; GIT bf56508 git://git.gnome.org/pan2)
Xref	csiph.com comp.lang.java.programmer:21462

Show key headers only | View raw

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       |

Thread

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

csiph-web