This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
From dev@openide.netbeans.org mailing list. Libor Kramolis wrote: --------------------- When we have automatic API/SPI signature test checker I would like to ask for publishing those modules API javadoc as openide already has. I propose http://www.netbeans.org/download/dev/apis/ path which will contain current dev openide javadoc as well as modules api/spi javadoc. Jesse Glick wrote: ------------------ One problem is that only a few people (RE) can actually update such URLs. It is awkward; a request for FTP access has been filed, so maybe in some years it will be better. :-) If RE can automatically generate such docs, it might be nice. Currently the website has the org.openide Javadoc (+ prose docs) as of the last stable release. Regularly updated dev docs might be nice too. But keeping that much stuff in CVS would be very unpleasant.
Accepting.
An implementation of #16811 would make this easier to do, esp. permitting it to be decentralized (managed by module owners).
Refined task: Jaroslav Tulach wrote: My answers: it looks like I misunderstood the task. Would you please negotiate on: 1) what java packages to include in javadoc? Just those that are part of officil API. By default any org.netbeans.api.* and org.netbeans.spi.* 2) does signature API tests share the list of packages for javadoc? Yes. where the list should be stored? It should be available to module writers that could add their own additional packages (org.apache.ant.netbeans.api) there. 3) how to press developers to use org.netbeans.api.** or org.netbeans.spi.** packages? Press? If a module wants to be part of official netbeans api, it either has to put classes into those packages and fullfil all steps associated with that or add its own package into the module api (less preferred) and follow the same steps. 4) consolidated/common target name? (I used name "javadoc" in the "most" of modules) Maybe, I do not have any opinion here. y.
Removing dependency to issue 16811, which makes no sense to me.
Re. #1/#2: if you can reliably find both (a) the module's sources and (b) the module's manifest, e.g. by assuming that src/ and manifest.mf are used respectively, then you can look for the manifest attribute OpenIDE-Module-Public-Packages which was introduced recently. If not present, the module owner has not specified a particular set of API packages, so perhaps do not generate Javadoc. If present, it may be just a hyphen ("-"), in which case there are no public packages; do not generate Javadoc. Otherwise, it will be one or more package names (separated by space and/or comma), each of which will end in ".*" (include that package in Javadoc) or ".**" (include that package and any subpackages in Javadoc). For example: OpenIDE-Module-Public-Packages: org.netbeans.api.ds.*, org.netbeans.spi.ds.* The same manifest attr both documents what the publically accessible API (or SPI) is, and actually enforces it at runtime inside NetBeans. Discussed in the dev (NB 3.4) Modules API. Does this sound like a good approach to others?
One minor correction. We do not want module writers to misuse org.netbeans.api and org.netbeans.spi so it might be also very good to check that if there is such package in the module, it is properly declared to the public. Implementation: We shall probably write an ant task to read the list of JavaDoc packages from a module, am I right?
I'm not sure what you mean by "misusing" these packages, can you clarify this a little? I guess an Ant task to do this stuff would work. It could look very simple: <nbmodulejavadoc dir="${nbroot}/openidex/looks" out="/tmp/javadoc"/> which would find the correct packages and sources automatically.
In the light of nbmodulejavadoc task. How should look result documentation? I ask because typical JavaDoc contains overview section (that is not a part of doc-files). There can be only one overview section for merged documentation. Will be the documentation merged?
Ruda, what is the progress?
Status: - got a list of modules to include in javadoc build: core/javahelp,core/settings,diff,java/api,java,lexer,mdr, openidex/looks,xml/api - found, that manifest key "OpenIDE-Module-Public-Packages:" is used just in core/javahelp. xml/api has strange definition of the value - double stars, newlines - is that OK? - merging javadocs is impossible at this time and it's hard to imagine a way how to merge it. The only way is to use multiple source directories, so you loose per-module overview option.
Re xml/api: Yes it is. Read Jesse's 2002-06-05 09:02 PDT comment. -- Is it necessary to merge modules' JavaDocs?
Well, Jesse didn't write anything about double stars and new line between ":" and "org....". Also it's not clear if it was wrapped to new line by Issuezilla or by Jesse. Maybe I missed something, but for me the value is still strange and is not easily readable for shell script automation. Also actually I'm not certain if I'll use it for scripting, but reformatting to one line would help.
Citation: ".**" (include that package and any subpackages in Javadoc) -- Multiline value is common in manifest, it is clearer to use new line for each value item.
Re. multiline format in manifests: it is explicitly permitted by the manifest specification, and java.util.jar.Manifest correctly reads it. However if it is going to cause big problems for shell-based scripting, I guess we can ask that people not split up the line in this way...
Well, tomorrow (Tuesday) will be a test day. Night build system is prepared to build it and upload to website. I have a few notes: - I didn't setup any connection between list of packages used by signature API tests and javadoc build - the javadoc will also build OpenAPI javadoc - manifests are not used for automated gathering of list of public packages - javadoc master index page is generated by shell script and is not much pretty - multiline values in manifest, of course, makes my life harder - I don't plan to implement Ant task nbmodulejavadoc, which seems to be very complex ... - every single javadoc package will be available for download (i.e. SettingsAPIs.zip JavahelpAPIs.zip etc), only .zips now - javadoc build is done by JDK 1.3.1_03, Ant 1.4.1 and Xalan 2.3.1 on classpath (xml/api requirement) - assumed two redundant locations will be: http://www.netbeans.org/dev/javadoc/index.html http://www.netbeans.org/dev/night/build200206250100/javadoc/index.html
Javadoc manually pushed on assumed target locations. Take a look on NetBeans public API javadoc at http://www.netbeans.org/dev/javadoc/index.html
David, thanks for reporting an error in URL. The proper URL to online javadoc is http://www.netbeans.org/download/dev/javadoc/index.html
Merged Javadoc might be nice too, to let you download one big ZIP and mount it. E.g. create an overview-summary.html showing links to individual summary pages, each of which would be renamed from an original overview-summary.html, and merge all other files together into one tree. Then you could search the whole thing at once. Not important though, just an idea.
Ruda, I read the whole issue and one thing is not clear to me: what should I do to get Ant module APIs published (org.apache.tools.ant.module.api)? Thanx.
Ruda if you could rename JavahelpAPIs to JavaHelpAPIs that would be nice. Not important. Can't do it myself or index page for all APIs would have a broken link.
Nice work. Please add -version parameter to the javadoc. Version info is important especially for modules...
Is @version actually important? Do you mean @since (which is included by default unless -nosince is passed)? Anyway this can be controlled on a per-module basis, and should be dealt with module owners IMHO - done in their own build scripts.
Set target milestone to TBD
This issue seems to be fixed. Reopen if necessary.
Ruda, you overlooked my question: what should I do to get Ant module APIs published (org.apache.tools.ant.module.api)?
Has not been built since Mon Aug 5, can you check on it please Ruda?
The Javadoc has not been published for over two weeks now.
This was partially affected by two main reasons: - transition of build system to Ant 1.4.1. There was hardcoded use of Ant 1.3 for NBM and javadoc builds and it failed when using nbantext.jar, which was compiled against Ant 1.4.1 - incomplete change in nbbuild/build.properties regarding change in configmods
Finally it's really fixed.
Removing dependency on issue 26824.