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.

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 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: References: <3b10d0bb-0307-4365-b762-d619fd3c608b@googlegroups.com> <50f6cebb$0$285$14726298@news.sunsite.dk> <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 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 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 |