Groups | Search | Server Info | Keyboard shortcuts | Login | Register

Groups > linux.debian.maint.java > #12934

Re: javadocs

Show all headers | View raw

Hi,

Le 2025-02-18 12:31, Emmanuel Bourg a écrit :
> - javadoc slows down the build, use more computing resources (the 
> -java-doc dependency resolution of maven-debian-helper at the end of 
> the build is extremely slow, and often inaccurate)

That's not much of an issue in my experience, and there is room for 
improvement in the maven-debian-helper.

> - -the java-doc packages fill more space on the mirrors

Some more stats then: I counted 189 MiB of -java-doc packages for 
bookworm, compared to 937 MiB of -java packages (which is surprisingly 
low, I was expecting 5x-10x more), which means that the -java-docs 
account for around 17% of the volume used by all java packages, which is 
reasonable. The whole bookworm archive is about 162 GiB in comparison, 
of which all -java-doc packages account for about 0.1%. I think we can 
call this a non-issue.

> - the inter -java-doc links are often broken, unless the build is 
> patched (more maintenance)
> - javadoc is often the source of reproducibility issues, the openjdk-21 
> package has 7 patches addressing some of these issues, and they have to 
> be updated for every new JDK release. There are also patches in Ant and 
> Maven.
> - jquery unbundling complexifies the build
> - every new JDK release over the past ten years came with new javadoc 
> issues. The tool is more and more strict, forcing us to rewrite the 
> documentations or use undocumented/unsupported flags to skip the 
> errors... until the next JDK reshuffles everything.

Some of these issues need to be fixed in the toolchain, eventually in 
the JDK itself, eventually by bringing to the attention of upstream 
developers (JDK, build tools) that backwards compatibility of that chain 
has been suboptimal so far to say the least and asking them to give more 
consideration to these issues in their developments, as maintainability 
matters for popularity.

> - javadocs sometimes contain Google Analytics scriplets or load 
> external resources, which cause privacy issues and must be patched out

I would argue here that it's actually a very good reason to provide 
alternatives that don't have these privacy issues.

> - https://javadoc.io is much more useful than our -java-doc packages

Not in my experience though. It lacks a proper index and a convenient 
search feature, fails to display some versions, and anyway not all java 
projects push their javadoc artifacts to Maven Central, gradle doesn't 
for example.

> The public API visible in the javadoc is rarely changed. Some notable 
> exceptions that come to mind are Guava, where removed code is often 
> reintroduced to preserve the backward compatibility, and the latest 
> iterations of the Servlet API for the same reason. But these changes 
> are just a convenience for Debian, developers will rather pull their 
> dependencies from Maven Central, and not from /usr/share/maven-repo. 
> Developing specifically for the Debian libraries is a non-sense for a 
> Java developer, why would I sacrifice cross-platform compatibility by 
> targeting a version of a library only available in Debian?

I was thinking more about the cases where features are dropped in the 
Debian versions (because of missing dependencies, security or licensing 
issues etc). The javadocs are a convenient place to document the 
deviations from upstream, reference bugs/discussions and eventually 
recommend ways to work around known issues.

> The javadoc can still be built locally from the source package, it's 
> just a couple of commands away:
> - apt source <package>
> - mvn javadoc:javadoc, or ant javadoc

... and then Maven happily downloads the entire Internet etc etc and 
then fails the build because of some of the issues above that are not 
fixed, unless Maven toolchains were configured to also download an 
entire older JDK to run that build. I would just download the javadoc 
jar from Maven Central or some upstream repository, or keep grepping the 
source code as is, that's faster and less trouble.

>> - they are convenient for working offline (which also happens in 
>> corporate settings, e.g. when deep inside a building where you won't 
>> pick up your operator's network, there is no guest network, and the 
>> corporate network has such an unfriendly and invasive policy that you 
>> won't even try to connect to it)
> 
> That's a corporate issue, not a Debian issue. A developer without 
> internet access is close to useless in 2025 anyway.

That was an example. We take permanent, high-speed, unrestricted 
Internet access for granted, but there are still many places and 
situations where being able to work offline is appreciated, if not a 
necessity.

> And yet we keep removing -java-doc packages and no user complains.

Fixing that: I'm hereby complaining here as one of them ^ ^

More seriously, there is a certain threshold that has to be crossed for 
users to start complaining or report issues. The fact that it's quiet so 
far doesn't mean everybody is happy with that.

>> Build issues are a fact, but I think that there are ways to 
>> drastically improve the situation, among other things by 
>> (automatically) testing new JDK or build tool releases before 
>> discovering compatibility issues as FTBFS bug reports pile up. A few 
>> other fixes in the toolchain are also needed, and I'm planning to work 
>> on these (testing and toolchains) later this year.
> 
> You can detect the issues automatically, but not fix them 
> automatically.

Sure, but this gives a chance to mitigate the issues in the build tools 
and document what needs to be done in the packages if anything. Also a 
part of the issue is that by policy we keep rebuilding older packages 
with newer JDKs, which has some advantages but is clearly diverging from 
the mainstream java practice where a given version is built once, 
artifacts are published and then that same version is never built again. 
This has some consequences that we have to deal with.

> I think the best would be to recognize that -java-doc packages are not 
> sustainable and of limited use. That doesn't mean we have to give up 
> any hope of documenting the Java APIs in Debian, it's just that the 
> -java-doc packages are not the right tool. In my opinion the right 
> approach would be to build a javadoc.debian.net service gathering the 
> javadoc of all Debian packages, similar to javadoc.io but specific to 
> Debian. And if it could also serve as a class search engine it would be 
> incredibly useful.

I also had this idea for an online service, and it's not mutually 
exclusive of -java-doc packages. Actually if you wanted to provide 
online javadocs that are built from Debian sources you would still have 
to do mostly the same work as what's required for producing -java-doc 
packages. In terms of logistics it's also much easier to have them 
packaged (e.g. they are guaranteed to be rebuilt with every new release 
of the main packages), and that would make it possible to distribute the 
webapp as a package that could be easily used in private deployments 
including one's own machine.

Do you (or others) happen to know a corporate sponsor that would be 
willing to provide the hosting or fund the service?

Cheers,

-- 
Julien Plissonneau Duquène

Back to linux.debian.maint.java | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-18 10:50 +0100
  Re: javadocs Emmanuel Bourg <ebourg@apache.org> - 2025-02-18 12:50 +0100
    Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:30 +0100
  Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:00 +0100
    Re: javadocs Julien Plissonneau Duquène <sre4ever@free.fr> - 2025-02-19 09:40 +0100

csiph-web