On Thu, Mar 09, 2006 at 09:28:36PM +0100, Arnaud Vandyck wrote: [...] > Eric@Lavar.de wrote: [...] > > Just my 5 cents: the policy about javadoc doesn't say where the javadoc > > should be registered in doc-base. I would suggest something like > > Programming/Java, in order to avoid have links all over the place in dhelp > > & Co. > > We have to decide where to register the doc, you are right. Your > suggestion seems fine. Is there any other proposals? [...] I have a proposal that I am far overdue in presenting regarding the registration of Javadoc for packages. I don't have much time currently, so I'll have to make this brief: Proposal for Registration of API Javadoc for Debian Java Packages The simplest way to show the proposed policy is to illustrate via an existing package as an example. The lucene source package is being used as the example here. Here is the content of the .doc-base file for the lucene-java-doc package: Document: liblucene-java-doc Title: API Javadoc for Apache Lucene Full-Text Search Library Author: Apache Lucene Project Team Abstract: This is the API Javadoc provided by the Apache Lucene Full-Text Search Library Section: Programming Format: HTML Index: /usr/share/doc/liblucene-java-doc/docs/index.html Files: /usr/share/doc/liblucene-java-doc/docs/*.html The idea here is to leverage simple default values. The "Document" element is by default the name of the documentation package. While there are other forms of documentation that exist for some packages (commons-httpclient comes to mind), the majority of the time programmers will be looking for the Javadoc of a particular package. The "Title" element follows the convention "API Javadoc for [meaningful, unique name]". Some existing packages have a value like "Javadoc API for [package name]"; this is incorrect. The document being registered is not the Javadoc API, and no package would have its own Javadoc API anyway. There are many packages that use a convention of "Programmer API for [binary package name for *-java-doc packge]"; this is not common English phrasing for Javadoc and should be abandoned in favor of the proposed convention. The "Author" element should by default reflect those who develop the software being packaged. The "Abstract" element follows the convention "This is the API Javadoc provided by [name of individual or team authoring the software being packaged]". There's no real benefit in trying to express the abstract more creatively for standard API Javadocs. The "Section" element is an area up for discussion, but it is critical that Java-related packages be categorized uniformly. Currently, many packages default to "Programming"; there is no "Programming/Java" Section. Python seems to have settled largely into the "Apps/Programming" section, and Perl doesn't seem to have settled into a section that I can find. "Programming" currently has no subsections that I can see, but I certainly think it is more intuitive than "Apps/Programming", particularly since most of our packages are libraries to be used by Java applications that employ them. In fact, few packages that have API Javadoc are are applications; most of them are libraries. The "Format" element should always have "HTML" as its value; Javadoc by its very nature is always HTML, barring some change in Javadoc functionality for JDKs, which is unlikely in the foreseeable future. The "Index" value should follow the convention of pointing to the root index.html file a the API Javadoc. Packages should also ensure that the root of the Javadoc generated by a package be uniformly located in /usr/share/doc/[binary java-doc package name]/docs. Not all upstream projects package Javadoc the same way; the Debian Java Packaging project should strive to unify Javadoc location to the degree that it is possible. The "Files" element should follow the convention of pointing to the folder housing the root index.html file of the generated API Javadoc, with a wildcard value of *.html. If the Javadoc convention of defaulting to .html suffixes ever changes, we will need to consider changing this element of our policy as well. That is what I had so far. Michael Koch also had an excellent suggestion of registering API Javadoc with devhelp, which I have not done yet with the packages I maintain, but it seems like a great idea. Hope that helps, -- Barry Hawkins All Things Computed site: www.alltc.com weblog: www.yepthatsme.com Registered Linux User #368650
Attachment:
signature.asc
Description: Digital signature