[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Suggestion for javadoc building

Hash: SHA1

Hello Mark,
> > > most libraries have api docs created with javadocs. When calling
> > > javadoc, links can be given to link to the used api's. I think there
> > > should be a central registry for all javadoc documentations installed.
> > > For this, I suggest a directory which links to all api doc directories.
> > > During javadoc creation, these directories could simply be included in
> > > the package building scripts. The packages using these links, then also
> > > have to depend and build-depend on the packages offering the used api
> > > docs. Later this can be automated by a wget spider or something else.
> gjdoc doesn't currently support -link, although hopefully it will in the
> future (If there are any java programmers listening who aren't busy at
> the moment...).
Never looked at it. I use the j2sdk from blackdown. But having these 
directories doesn't imply, that they have to be used, only should if 

> This might not be easier for package scripts as the maintainers would
> have to build-depend on each -doc package and also -link dir, where each
> api doc directory is listed (javadoc looks for a single package-list
> file in each directory).
I know they have to list all. But this can be supported by debhelper. The 
dependencies could also be checked after compiling. When the binary is 
generated, the build dependencies can be checked against the needed packages 
via the links.

> However, having everything in a central
> location and all links pointing there might be a good idea, especially
> from the user POV.
Thats another argument. I think having it in the policy can only be useful. 
When it's there, debhelper tools can be created easily.

> I guess work will have to be done on policy after gjdoc is working and
> in Debian,
Hmm. I think gjdoc will be compatible with javadoc when it supports link. And 
until there, javadoc will be used by most users. And I think, when it is 
avalaible, the most will still use javadoc (or another alternative being 
called javadoc and having the same command line api).

> but one question I have is how should interlinking java
> packages dependencies be handled?
First the maintainers of the java-packages can suggest what they need for 
using them. I think the most use ant or make. The make users need a script 
which outputs the parameters, like with pkg-config, the ant users simply take 
all directories in the directory containing the links to the javadocs (via 
The last would be dh_java which checks against the build-dependencies and 
outputs the normal dependencies. Generating them can be done after the docs 
are created. Via a shell script and a link spider, all local links can be 
extracted. Then the packages can be resolved via the dpkg database.

> We will have a general java api documentation package generated from
> classpath sources.
No, all packages will have their seperate documentation, but link to files in 
other packages on which they depend.

> Libraries could then build javadoc linking against this.
Against those packagES you mean? Yes.

> Then, when a user wants the documentation for one library, will he
> also have to download the entire core java api docs and api for any
> linked libraries?
When he whats to recompile the package yes. When he doesn't, that depends on 
what dependencies we create.

> or is it appropriate to just Recommend the other
> packages and have broken links?
It's a question of policy. I think it should be debian policy, not only debian 
java policy, to have no broken links. So I think depend is the best, the 
others should use equivs.

> or are there any better solutions?
Yes, there is. As long as the documentation is also in the internet. A script 
could check if the other documentation packages are installed and change the 
links for local file's or online versions as necessary. But I think this is 
overkill. I think most people using java for development have relativly fast 
computers and enough disk space. So why bother.

With kind regards
	Torsten Knodt
Version: GnuPG v1.2.0 (GNU/Linux)


Reply to: