master apidoc links fixes (partial) by ebarboni · Pull Request #4450 · apache/netbeans

ebarboni · 2022-07-29T17:41:11Z

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 · 2022-07-30T13:03:41Z

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 · 2022-08-01T14:43:39Z

@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 · 2022-08-01T14:56:28Z

@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 · 2022-08-01T14:59:36Z

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

ebarboni · 2022-08-01T16:22:44Z

@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 · 2022-08-01T16:34:35Z

@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 · 2022-08-04T17:18:53Z

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 · 2022-08-04T17:31:07Z

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 · 2022-08-12T16:44:49Z

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 · 2022-08-12T16:54:02Z

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 · 2022-08-12T18:33:41Z

nbbuild/javadoctools/template.xml

+    <target name="javadoc-exec-packages" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title,javadoc-exec-condition,-javadoc-set-footer,-javadoc-exec-packages-jdk,-javadoc-exec-packages-nbjavac" unless="javadoc.exec.packages">
+        <!-- javadoc-exec-packages-jdk  -->
+        <!-- javadoc-exec-packages-nbjavac  -->
+    </target>
+


previous target javadoc-exec-packages depends on -javadoc-exec-packages-jdk and javadoc-exec-packages-nbjavac

ebarboni · 2022-08-12T18:34:48Z

nbbuild/javadoctools/template.xml

+            <arg value="-notimestamp" />
+        </javadoc>
+    </target>
+    <target name="-javadoc-exec-packages-jdk" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title,javadoc-exec-condition,-javadoc-set-footer" unless="javadoc.nbjavac">


target -javadoc-exec-package-jdk is active only if javadoc.nbjavac is not set

ebarboni · 2022-08-12T18:39:30Z

nbbuild/javadoctools/template.xml

-        <javadoc source="${javac.source}" author="false" destdir="${javadoc.out.dir}" packagenames="${javadoc.packages}" stylesheetfile="${javadoc.css.main}" windowtitle="${javadoc.title}" overview="${javadoc.overview}" splitindex="true" use="true" version="false" useexternalfile="true" encoding="UTF-8">
+
+
+    <target name="-javadoc-exec-packages-nbjavac" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title,javadoc-exec-condition,-javadoc-set-footer" if="javadoc.nbjavac">


-javadoc-exec-packages-nbjavac target only active javadoc.nbjavac
currently as mentioned only 2 modules need that. javadoc in this case not fail if error.
it's possible to test on module java.source.base. ant clean;ant build; ant javadoc.

As this target is not working cannot prepend the bootclasspath with nb-javac-jdk this lead to this module not visible in the apidoc (except their arch,apichanges)

ebarboni · 2022-08-12T18:58:51Z

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 · 2022-08-29T15:34:50Z

@mbien hope the commit split in enough.

mbien

i only glanced over the first commit since it touches over 1k files which makes it hard to review.

The rest looks ok as far as I can tell. Good that the javadoc.nbjavac trick works. I left one comment inline.

Since this is such a big changeset, i would recommend to split it into two commits, one which changes ant logic and actual source code logic and another which fixes all the links and other javadoc issues. So that we don't hide important changes in all the cleanup noise.

nbbuild/javadoctools/template.xml

sdedic

Reviewed up to harness cluster ... will continue. Sorry - it's terribly long :)

enterprise/j2eeserver/src/org/netbeans/modules/j2ee/deployment/devmodules/api/J2eePlatform.java

...rprise/j2eeserver/src/org/netbeans/modules/j2ee/deployment/plugins/spi/J2eePlatformImpl.java

sdedic · 2022-09-14T08:44:56Z

extide/gradle/src/org/netbeans/modules/gradle/api/execute/ActionMapping.java

 * The mapping can cause the action to be <b>disabled</b>: if {@link #getReloadRule()} == {@link ReloadRule#NEVER} and
- * {@link #getArgs()} == {@code null}. Such mapping had no effect in previous versions. This can be checked by a
- * convenience method {@link RunUtils#isActionDisabled}.
+ * {@link #getArgs()} == {@code null}. Such mapping had no effect in previous versions.


reason to remove the mention to isActionDisabled ?

this method is no more present.

@sdedic is it ok to resolve this ?

sdedic · 2022-09-14T08:46:33Z

extide/gradle/src/org/netbeans/modules/gradle/api/execute/GradleExecConfiguration.java

 * <p>
 * GradleExecConfigurations can be also declared by a Plugin that implements a
- * <a href="@TOP@/org/netbeans/spi/GradleActionsProvider.html#define-configuration">GradleActionsProvider</a>,
+ * {@link org.netbeans.modules.gradle.spi.actions.GradleActionsProvider GradleActionsProvider },


The original link points directly to the example code (using anchor)

The anchor is not working because not present that why I try to use the link to the class

@sdedic is it ok to resolve this ?

harness/nbjunit/src/org/netbeans/junit/NbModuleSuite.java

sdedic · 2022-09-14T09:00:19Z

ide/api.debugger/src/org/netbeans/api/debugger/ActionsManager.java

     * Post action on this DebuggerEngine.
     * This method does not block till the action is done,
-     * if {@link #canPostAsynchronously} returns true.
+     * if <code>canPostAsynchronously</code> returns true.


better @link to the method ?

method is not existing and cannot be linked. Not sure on how to rewrite

// cc: @entlicher ?

ebarboni · 2022-09-14T14:40:58Z

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

ebarboni · 2022-11-21T11:31:12Z

will be reworked per clusters. Changes should be the same

BradWalker · 2023-03-04T00:48:31Z

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.

ebarboni requested review from dbalek, jlahoda, jtulach and sdedic July 29, 2022 17:41

ebarboni added the doc Documentation related PRs label Aug 3, 2022

ebarboni force-pushed the fixapimasterdoc branch 2 times, most recently from 9549d9b to 5cb0f24 Compare August 8, 2022 16:28

ebarboni commented Aug 12, 2022

View reviewed changes

ebarboni force-pushed the fixapimasterdoc branch from 591b5f0 to f66a27b Compare August 29, 2022 15:21

fix links detection + fixes for javadoc errors on master

7a4a3bf

ebarboni force-pushed the fixapimasterdoc branch from f66a27b to 7a4a3bf Compare August 29, 2022 15:31

target changes for ant javadoc

9dde049

ebarboni added 4 commits September 1, 2022 13:09

Merge branch 'apache:master' into fixapimasterdoc

8aae0bd

additionnal fix post rebase

664f326

remove patch module as it fail

705373f

maintains jdk 8 for antsrc

d7c0596

ebarboni requested a review from mbien September 13, 2022 10:45

mbien reviewed Sep 14, 2022

View reviewed changes

nbbuild/javadoctools/template.xml Outdated Show resolved Hide resolved

sdedic reviewed Sep 14, 2022

View reviewed changes

ebarboni added 4 commits September 14, 2022 16:06

link on new netbeans website update disallowed-links

37a5bc5

gradle apichanges fix

178b6ca

fix NbModuleSuite according to sdedic

46ede0c

fix entreprise j2eeserver sdedic comment

0d440f1

ebarboni added this to the NB16 milestone Sep 20, 2022

neilcsmith-net modified the milestones: NB16, NB17 Oct 19, 2022

ebarboni mentioned this pull request Nov 15, 2022

apidoc check and improvement #4969

Merged

ebarboni closed this in #4969 Nov 21, 2022

ebarboni mentioned this pull request Jan 5, 2023

apidoc error/warning fix #5216

Merged

ebarboni mentioned this pull request Feb 3, 2023

Fixed javadoc tags #5419

Merged

ebarboni mentioned this pull request Feb 24, 2023

apidoc error/warning fix (#2) #5561

Merged

ebarboni mentioned this pull request Mar 7, 2023

apidoc error/warning fix (#3) #5623

Merged

ebarboni mentioned this pull request Mar 17, 2023

apidoc error/warning fix (#4) #5672

Merged

This was referenced Mar 24, 2023

apidoc error/warning fix (#5) #5712

Merged

apidoc error/warning fix (#6) #5734

Merged

apidoc fixes #5741

Merged

ebarboni mentioned this pull request Mar 31, 2023

apidoc master branch links fix #5755

Merged

		<javadoc source="${javac.source}" author="false" destdir="${javadoc.out.dir}" packagenames="${javadoc.packages}" stylesheetfile="${javadoc.css.main}" windowtitle="${javadoc.title}" overview="${javadoc.overview}" splitindex="true" use="true" version="false" useexternalfile="true" encoding="UTF-8">


		<target name="-javadoc-exec-packages-nbjavac" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title,javadoc-exec-condition,-javadoc-set-footer" if="javadoc.nbjavac">

Conversation

ebarboni commented Jul 29, 2022

Uh oh!

mbien commented Jul 30, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ebarboni commented Aug 1, 2022

Uh oh!

mbien commented Aug 1, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

neilcsmith-net commented Aug 1, 2022

Uh oh!

ebarboni commented Aug 1, 2022

Uh oh!

mbien commented Aug 1, 2022

Uh oh!

ebarboni commented Aug 4, 2022

Uh oh!

mbien commented Aug 4, 2022

Uh oh!

ebarboni commented Aug 12, 2022

Uh oh!

mbien commented Aug 12, 2022

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ebarboni commented Aug 12, 2022

Uh oh!

ebarboni commented Aug 29, 2022

Uh oh!

mbien left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sdedic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ebarboni Sep 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ebarboni commented Sep 14, 2022

Uh oh!

ebarboni commented Nov 21, 2022

Uh oh!

BradWalker commented Mar 4, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mbien commented Jul 30, 2022 •

edited

Loading

mbien commented Aug 1, 2022 •

edited

Loading

ebarboni Sep 14, 2022 •

edited

Loading