master apidoc links fixes (partial)

[ebarboni]

HI @jtulach I tried the approach on master too.

with jdk 11 some warning are now error I guess and prevent the javadoc generation I try to fix some of the issue I encounter.

Missing element are error (i.e Bundle so I introduced) a new path element in the javadoc task

For the moment I have 63 lines of bad links.

most of them are related to https://github.com/apache/netbeans/tree/master/java/java.source.base (as an example) org.netbeans.modules.java.source.builder issue it that javadoc cannot find the com.sun.source.tree.CaseTree.CaseKind; I compile on jdk 11 and this is introduced in jdk 12 or maybe with the nb-javac.

What would be a good method to handle that ?

[mbien]

org.netbeans.modules.java.source.builder issue it that javadoc cannot find the com.sun.source.tree.CaseTree.CaseKind; I compile on jdk 11 and this is introduced in jdk 12 or maybe with the nb-javac.

what if we generate the javadoc with the same JDK of the current nb-javac version? So for master it would be JDK 18 right now.

Due to nb-javac, NetBeans builds a little bit of a frankenstein JDK at runtime. Since java is forward compatible API-wise, JDK 18 should hopefully cover all APIs which are used in NBs.

[ebarboni]

@mbien this could be done in a CI build but how to do that at the time you edit the module within IDE for example.

[mbien]

@mbien this could be done in a CI build but how to do that at the time you edit the module within IDE for example.

I don't think this is a problem. NB can be built on current JDKs thanks to the updates in 13 and 14.

We could let it print a warning and skip the javadoc build: "javadoc build of this module requires running on the same JDK version as nb-javac is based on"

but maybe this isn't even needed. Javadoc is a separate target it isn't build by default anyway - not many would notice. As long we can generate and host docs somehow its all good IMO.

edit: does it work if you build the doc with 18? ;)

[neilcsmith-net]

Could "we" publish javadocs for nbjavac? And if we did, could we link to them?

[ebarboni]

@mbien building too ahead make some module not compilable (source target too low 1.6 for openide.io as an example)

I have now idea if we can mix javadoc from nbjavac + current jdk.

there are a lots of forward reference to modules that are not in build classpath and need the replace @see and @link are very strict.

[mbien]

@mbien building too ahead make some module not compilable (source target too low 1.6 for openide.io as an example)

i think we could rise everything to 8 if necessary. Even the profiler is using 8. Nothing is tested on 1.6.

[ebarboni]

I will later sqash all of that in one commit so we could resync. on true master branch :D I've miss the -meta.branch=master I can build until the end with no more javadoc error. Will try to fix remaining issue.

[mbien]

I will later sqash all of that in one commit so we could resync. on true master branch :D I've miss the -meta.branch=master I can build until the end with no more javadoc error. Will try to fix remaining issue.

this was a lot of work @ebarboni, good job!

[ebarboni]

removed the discussion as ported to dev.

I tried to use --patch-module but withtout success. Xbootclasspath/a is the only allowed args but Xootclasspath/p is needed I think.

waiting for PR on website site to alter the missing link.

Introducing: javadoc.nbjavac=true

to allow a choice in nbbuild/javadoctools/templates.xml because now javadoc-exec-packages is composed of javadoc-exec-packages-nbjavac or javadoc-exec-packages-jdk according to the boolean.

2 modules needs the boolean set: java.source.base spi.java.hints

[mbien]

this is going to be difficult to review :/

would it be possible to split "interesting" changes like the build logic for javadoc.nbjavac=true into separate commits?

[ebarboni]

I try to put emphasis on the part that change according to the javadoc.nbjavac flag. it's if unless ant contional as done in many place in our build file.

The only issue is within the javadoc target using nbjavac I've no idea on how to make it work -J-Xbootstrap/p is not available only -J-Xbootstrap/a but this fail. --patch-module fail too

I find it difficult to split as I would like to get the last link error done. The one linking to *netbeans.org/ and blots landing to useless 404 pages (pr in progress to website). All changes in templates.xml is because got lots of fixes to do like replacing @element@ deeper, filtering on special index files or deprecated list. Snippet was to short with only 120 line. Adding generated path to get bundle linked too.

[ebarboni]

@mbien hope the commit split in enough.

[ebarboni]

I will later squash all this in one commit but I try to keep the commit per module for helping review

[ebarboni]

will be reworked per clusters. Changes should be the same

[BradWalker]

Hey @ebarboni , could I possibly help with this? It's interesting to me and I could learn some new stuff. I would need some guidance so that I don't already duplicate your work.