Errors and warnings in javadoc during verification build #1109

merks · 2023-09-13T12:12:09Z

When building #1108 the following errors and warnings are reported:

11:24:15.294 [ERROR] MavenReportException: Error while generating Javadoc: 
Exit code: 1 - /home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:55: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:56: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:56: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/internal/ExpandableNode.java:95: warning: {@return} not at beginning of description
	 * {@return current offset in the original list of elements}
	   ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/internal/ExpandableNode.java:112: warning: {@return} not at beginning of description
	 * {@return all remaining elements from original array starting with the element
	   ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:122: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:122: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_PR-1108/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
9 errors
2 warnings

The text was updated successfully, but these errors were encountered:

marcushoepfner · 2023-09-19T05:54:56Z

similar to #1103 (?)

akurtakov · 2023-09-19T05:59:16Z

These are not similar, what @merks posted here is actually & that is not escaped aka & amp;

merks · 2023-09-19T06:07:06Z

I noticed very many such errors, ones that apparent to have been around for a very long time. It seems only the verification build logs/reports these errors, which really do look like things that ought to be fixed because it's really annoying for the verification build to be a sea of errors which appear to be ignored in terms of the build success/failure making it hard to find the "real" errors if any...

akurtakov · 2023-09-19T06:15:15Z

Where do you see it ? E.g. in https://github.com/eclipse-platform/eclipse.platform.ui/pull/1099/checks?check_run_id=16887602248 I don't see them.

merks · 2023-09-19T06:26:47Z

Good question. There are so many builds and I don't recall which one had all those errors in the log.

These do look wrong though:

So something should be reporting them, or if not, something reported them when I copied the errors from "the log".

akurtakov · 2023-09-19T06:48:50Z

Javadoc is still in terrible state and was even worse and I've spent days improving it bit by bit which is extremely tedious process. It got to a state where "certain" things are clean and new issues fail the build so I would like first to get to a point where verifications are stable so people don't have an excuse to ignore them.

laeubi · 2023-09-19T06:53:52Z

making it hard to find the "real" errors if any...

Why are Javadoc errors not "real"? ... the inital purpose of this is/was to make people aware of Javadoc errors that otherwise only reported on the next i-build (if one looks there at the logs).

Nerveless no one really needs to scan the logs, we have scanners for this for example here (the linked PR is already merged so build logs are gone):

https://ci.eclipse.org/platform/job/eclipse.platform.ui/job/master/23/

Also if you look at the summary here you get some parsed problems, I did this mostly for API Tools Errors/Warnings:

https://github.com/eclipse-platform/eclipse.platform.ui/actions/runs/6171755924

Also the Github Action Checks give a comprehensive summary for the cautious reviewer:

merks · 2023-09-19T07:03:38Z

@laeubi

This is why I put "real" in quotes. Obviously they are real yet this has been this way for a long time. Clearly I did scan logs or I would not have been able to copy and paste the log content into this issue. The question now is why did I find such errors in "the log" yet the current the logs says everything is fine and good.

Moreover, is it a "real" problem to use & in Javadoc directly rather than using & or is it not "real" a problem? And, if not a "real" problem, why was the log I saw full of such errors? If I'd known the problem of reported Javadoc errors wasn't generally reproducible, I would have take more care to keep track of where I found the errors...

laeubi · 2023-09-19T07:12:30Z

Moreover, is it a "real" problem to use & in Javadoc directly rather than using &

If you use the ampersand inside html tags, yes and that's what the tool complains about see:

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html > Write Comments in HTML

entities for the less than symbol (<) and the greater than symbol (>) should be written as < and >. Similarly, the ampersand (&) should be written as &.

about reproducibility, as we have special builds that replace artifacts with baseline a tool like javadoc might decide to not run because everything seems up-to-date, but that's only a guess unless one can see a build log of "not reproducibility" (please note that this is a special maven term and eclipse builds are in general not reproducible anyways)

laeubi · 2023-09-19T07:32:13Z

By the way I noticed some unnecessary maven warnings in the logs, should be fixed with:

add build-helper-maven-plugin to pluginManagement section eclipse.platform.releng.aggregator#1373

laeubi · 2023-09-19T07:37:01Z

I created an issue at p2 as well about another source of many warnings that fill the log here:

Problems resolving provisioning plan with osgi.contract eclipse-equinox/p2#322

laeubi · 2023-09-19T07:44:14Z

If I scan the consoleLog of the build I see this error:

16:12:14.912 [INFO] --- javadoc:3.0.1:jar (attach-javadocs) @ org.eclipse.jface ---
16:12:24.823 [ERROR] MavenReportException: Error while generating Javadoc: 
Exit code: 1 - /home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:55: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:56: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/AbstractControlFactory.java:56: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/internal/ExpandableNode.java:95: warning: {@return} not at beginning of description
	 * {@return current offset in the original list of elements}
	   ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/viewers/internal/ExpandableNode.java:112: warning: {@return} not at beginning of description
	 * {@return all remaining elements from original array starting with the element
	   ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:122: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TableColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:122: error: bad HTML entity
	 * The mnemonic indicator (character '&') is not displayed in a tool tip. To
	                                      ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                     ^
/home/jenkins/agent/workspace/eclipse.platform.ui_master/bundles/org.eclipse.jface/src/org/eclipse/jface/widgets/TreeColumnFactory.java:123: error: bad HTML entity
	 * display a single '&' in the tool tip, the character '&' can be escaped by
	                                                        ^
9 errors
2 warnings

so it seems to be well reproducible but the Jenkins Javadoc scanner seems not to find it.
Instead it is classified as a Maven Problem:

https://ci.eclipse.org/platform/job/eclipse.platform.ui/job/master/23/maven-warnings/moduleName.657231328/

by the way, currently the build is configured to not fails on javadoc problems ... so that why it show as ERROR in the log but not make the build itself fail...

merks · 2023-09-19T07:55:35Z

Excellent detective work!

laeubi · 2023-09-19T11:54:42Z

It seems even that this is specific to the HTML encoding problem where it is currently not handled so nice in this PR I see javadoc annotations just as expected:

(not that it seems people are bothering much more either if they are shown ;-)

HeikoKlare · 2024-01-18T14:08:48Z

The last remaining javadoc errors that can be found in build logs should be fixed with:

Fix remaining javadoc errors #1516

@merks @laeubi Do you see anything left to do here or any reason to keep this issue open afterwards?

merks mentioned this issue Sep 13, 2023

Eliminate includes of bundles transitively required by batik #1108

Merged

laeubi linked a pull request Jan 18, 2024 that will close this issue

Fix remaining javadoc errors #1516

Merged

HeikoKlare closed this as completed in #1516 Jan 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Errors and warnings in javadoc during verification build #1109

Errors and warnings in javadoc during verification build #1109

merks commented Sep 13, 2023

marcushoepfner commented Sep 19, 2023

akurtakov commented Sep 19, 2023 •

edited

Loading

merks commented Sep 19, 2023

akurtakov commented Sep 19, 2023

merks commented Sep 19, 2023

akurtakov commented Sep 19, 2023

laeubi commented Sep 19, 2023

merks commented Sep 19, 2023

laeubi commented Sep 19, 2023 •

edited

Loading

laeubi commented Sep 19, 2023

laeubi commented Sep 19, 2023

laeubi commented Sep 19, 2023

merks commented Sep 19, 2023

laeubi commented Sep 19, 2023

HeikoKlare commented Jan 18, 2024

Errors and warnings in javadoc during verification build #1109

Errors and warnings in javadoc during verification build #1109

Comments

merks commented Sep 13, 2023

marcushoepfner commented Sep 19, 2023

akurtakov commented Sep 19, 2023 • edited Loading

merks commented Sep 19, 2023

akurtakov commented Sep 19, 2023

merks commented Sep 19, 2023

akurtakov commented Sep 19, 2023

laeubi commented Sep 19, 2023

merks commented Sep 19, 2023

laeubi commented Sep 19, 2023 • edited Loading

laeubi commented Sep 19, 2023

laeubi commented Sep 19, 2023

laeubi commented Sep 19, 2023

merks commented Sep 19, 2023

laeubi commented Sep 19, 2023

HeikoKlare commented Jan 18, 2024

akurtakov commented Sep 19, 2023 •

edited

Loading

laeubi commented Sep 19, 2023 •

edited

Loading