Bugzilla – Full Text Bug Listing
| Summary: | Javadoc error related to #MAX_RESOURCES_TO_TRANSFER | ||||||
|---|---|---|---|---|---|---|---|
| Product: | [Eclipse Project] Platform | Reporter: | David Williams <david_williams> | ||||
| Component: | Doc | Assignee: | Andrey Loskutov <loskutov> | ||||
| Status: | VERIFIED FIXED | QA Contact: | |||||
| Severity: | normal | ||||||
| Priority: | P3 | CC: | daniel_megert, eclipse.sprigogin, Lars.Vogel, loskutov, markus.kell.r | ||||
| Version: | 4.5 | ||||||
| Target Milestone: | 4.5 M6 | ||||||
| Hardware: | All | ||||||
| OS: | All | ||||||
| See Also: |
https://git.eclipse.org/r/42029 https://git.eclipse.org/r/42030 https://git.eclipse.org/c/platform/eclipse.platform.ui.git/commit/?id=4f27b39c3e0e65f9107c4bf74836337a2b3fe6e5 https://git.eclipse.org/c/platform/eclipse.platform.ui.git/commit/?id=046a3292284b94f99fbde9505eaccfdae12c786b |
||||||
| Whiteboard: | |||||||
| Attachments: |
|
||||||
|
Description
David Williams
I know there was one "doc change" related to bug 453228, but off hand doesn't seem like it would be related to org.eclipse.ui.ide unless part of it was "completely wrong". But, this sounds like might be related to something else? Lars, not sure why I think it might be related to changes you've been making? :) But thought it worth asking. Sergey, From a very quick look, it appears you might have made some changes in this area of code/doc ... so, thought I'd CC you in case it appeared familiar? Ok, tracked a little more ... and I think related to changes made in bug 205678. (Lars and Andrey Loskutov). Coming from https://git.eclipse.org/r/#/c/39996 Is it true - javadoc can't reference to private field values? Eclipse doesn't warn me about it. David, which javadoc version is in use? Created attachment 250855 [details] Screenshot of project settings (In reply to David Williams from comment #0) > The N20150216-2000 build had a "releng test" failure, due to the expected > content in this log: > > http://download.eclipse.org/eclipse/downloads/drops4/N20150216-2000/ > compilelogs/platform.doc.isv.javadoc.txt > > which said: > > ../../../eclipse.platform.ui/bundles/org.eclipse.ui.ide/extensions/org/ > eclipse/ui/part/ResourceTransfer.java:59: warning - > #MAX_RESOURCES_TO_TRANSFER (referenced by @value tag) is an unknown > reference. > 1 warning Which access level is allowed to use in Javadoc? Package or Protected? We should configure the project accordingly. (In reply to Lars Vogel from comment #5) > Created attachment 250855 [details] > Screenshot of project settings > > (In reply to David Williams from comment #0) > > The N20150216-2000 build had a "releng test" failure, due to the expected > > content in this log: > > > > http://download.eclipse.org/eclipse/downloads/drops4/N20150216-2000/ > > compilelogs/platform.doc.isv.javadoc.txt > > > > which said: > > > > ../../../eclipse.platform.ui/bundles/org.eclipse.ui.ide/extensions/org/ > > eclipse/ui/part/ResourceTransfer.java:59: warning - > > #MAX_RESOURCES_TO_TRANSFER (referenced by @value tag) is an unknown > > reference. > > 1 warning > > Which access level is allowed to use in Javadoc? Package or Protected? We > should configure the project accordingly. Everything that is part of the API. New Gerrit change created: https://git.eclipse.org/r/42029 New Gerrit change created: https://git.eclipse.org/r/42030 (In reply to Dani Megert from comment #6) > > Which access level is allowed to use in Javadoc? Package or Protected? We > > should configure the project accordingly. > > Everything that is part of the API. Dani, Lars, please review https://git.eclipse.org/r/42030 which changes the Platform UI settings. (In reply to Lars Vogel from comment #5) > Which access level is allowed to use in Javadoc? Package or Protected? We > should configure the project accordingly. Note that the preferences only specify which members are validated. Which members are being generated by Javadoc later, is out of the compiler's knowledge. For Eclipse we generated Javadoc for APIs only, and hence we cannot reference members that are not API or are below protected visibility. (In reply to Andrey Loskutov from comment #4) > Coming from https://git.eclipse.org/r/#/c/39996 > > Is it true - javadoc can't reference to private field values? > Eclipse doesn't warn me about it. > > David, which javadoc version is in use? We use the "javadoc" executable from 1.8, if that's that you mean. I really don't know about private/protected JavaDoc issues ... but ... if it is private (and static final), does it really need to be in "javadoc"? Or, would a simple comment suffice? (In reply to Dani Megert from comment #10) > (In reply to Lars Vogel from comment #5) > > Which access level is allowed to use in Javadoc? Package or Protected? We > > should configure the project accordingly. > > Note that the preferences only specify which members are validated. Which > members are being generated by Javadoc later, is out of the compiler's > knowledge. For Eclipse we generated Javadoc for APIs only, and hence we > cannot reference members that are not API or are below protected visibility. So the setting should be "Only consider members as visible as 'protected'", right? So if I change the settings accordingly, Eclipse shows me the right warning that I can't reference MAX_RESOURCES_TO_TRANSFER. Therefore I proposed https://git.eclipse.org/r/42030 which would warn committers before they build fail. But why then you told that the setting is not related (In reply to David Williams from comment #11) > (In reply to Andrey Loskutov from comment #4) > > Coming from https://git.eclipse.org/r/#/c/39996 > > > > Is it true - javadoc can't reference to private field values? > > Eclipse doesn't warn me about it. > > > > David, which javadoc version is in use? > > We use the "javadoc" executable from 1.8, if that's that you mean. Yes, I meant exactly this. AFAIK 1.8 is more strict. > I really don't know about private/protected JavaDoc issues ... but ... > if it is private (and static final), does it really need to be in "javadoc"? > Or, would a simple comment suffice? The javadoc was not referring to the *name* but to the *value* of the field, so this shouldn't be a problem anyway - but obviously the javadoc isn't smart enough. (In reply to Andrey Loskutov from comment #12) > (In reply to Dani Megert from comment #10) > > (In reply to Lars Vogel from comment #5) > > > Which access level is allowed to use in Javadoc? Package or Protected? We > > > should configure the project accordingly. > > > > Note that the preferences only specify which members are validated. Which > > members are being generated by Javadoc later, is out of the compiler's > > knowledge. For Eclipse we generated Javadoc for APIs only, and hence we > > cannot reference members that are not API or are below protected visibility. > > So the setting should be "Only consider members as visible as 'protected'", > right? So if I change the settings accordingly, Eclipse shows me the right > warning that I can't reference MAX_RESOURCES_TO_TRANSFER. > > Therefore I proposed https://git.eclipse.org/r/42030 which would warn > committers before they build fail. Right, the setting actually does two things: it specifies which elements are checked, and also sets the scope for the reference validation. Gerrit change https://git.eclipse.org/r/42029 was merged to [master]. Commit: http://git.eclipse.org/c/platform/eclipse.platform.ui.git/commit/?id=4f27b39c3e0e65f9107c4bf74836337a2b3fe6e5 Gerrit change https://git.eclipse.org/r/42030 was merged to [master]. Commit: http://git.eclipse.org/c/platform/eclipse.platform.ui.git/commit/?id=046a3292284b94f99fbde9505eaccfdae12c786b (In reply to Andrey Loskutov from comment #12) > The javadoc was not referring to the *name* but to the *value* of the field, > so this shouldn't be a problem anyway - but obviously the javadoc isn't > smart enough. Yes, it refers to the value, but the Javadoc tool wants to put a link to the Javadoc of the referenced member. The tool could simply put in the value, but it would still issue the warning. Thanks Andrey for the fast fixes. (In reply to David Williams from comment #11) > We use the "javadoc" executable from 1.8, if that's that you mean. That would also be OK, but we actually use the Javadoc tool from 1.7.0_51. The buildDoc.xml scripts try to use a ${javadoc16} variable, but this is apparently not set anywhere, so we fall back to ${javadoc}, which is initialized to ${java.home}/../bin/javadoc For the records: The Javadoc tool description doesn't specify this situation: http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html Javadoc 8 doesn't even report a warning any more. I filed a bug at http://bugreport.java.com/submit_start.do with the information below (Oracle's Review ID: JI-9019100) Javadoc 8 misses warning for unsupported @value reference to private member =========================================================================== /** * {@value #MAX_RESOURCES_TO_TRANSFER} elements * @see #MAX_RESOURCES_TO_TRANSFER */ public class ResourceTransfer { private final static int MAX_RESOURCES_TO_TRANSFER= 1000 * 1000; } Generate Javadoc for this class using javadoc -protected. Java 8: - does not produce any warning - silently skips "{@value #MAX_RESOURCES_TO_TRANSFER}" in the generated html => information is lost - creates a "See Also:" link that points to an nonexistent anchor Java 7: - produces a correct warning: Generating ...\doc\ResourceTransfer.html... ...\src\ResourceTransfer.java:5: warning - #MAX_RESOURCES_TO_TRANSFER (referenced by @value tag) is an unknown reference. - skips "{@value #MAX_RESOURCES_TO_TRANSFER}" in the generated html => information is lost - creates a "See Also:" link that points to an nonexistent anchor (warning was missing here as well) A similar issue has been discussed before, and the conclusion was that there should be a warning for all references to members that are excluded from Javadoc processing (e.g. via -protected): https://bugs.openjdk.java.net/browse/JDK-4108538 (In reply to Markus Keller from comment #18) > (In reply to David Williams from comment #11) > > We use the "javadoc" executable from 1.8, if that's that you mean. > > That would also be OK, but we actually use the Javadoc tool from 1.7.0_51. > The buildDoc.xml scripts try to use a ${javadoc16} variable, but this is > apparently not set anywhere, so we fall back to ${javadoc}, which is > initialized to ${java.home}/../bin/javadoc Hmmm, guess this is getting off topic, but perhaps only Luna had the change? In our "production builds" we set a special variable, because didn't seem to be an easy way to do it with toolschain.xml ... complete with comments (I know there is a bug about this somewhere): # custom, environment specific setting, required to generate java doc correctly for Java 8 additions, # in our production builds. This is anticipated to be temporary, until we find a better way # to do it. export JAVA_DOC_TOOL="-Declipse.javadoc=/shared/common/jdk1.8.0_x64-latest/bin/javadoc" Or, maybe someone found a better way to do it? (In reply to David Williams from comment #19) Thanks for mentioning this. Opened bug 460146 to move all doc bundles to Java 8. |