Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 375409

Summary: Add missing Javadoc compile options to batch compiler
Product: [Eclipse Project] JDT Reporter: Alexander Weickmann <alexander.weickmann>
Component: CoreAssignee: Ayushman Jain <amj87.iitr>
Status: VERIFIED FIXED QA Contact:
Severity: normal    
Priority: P3 CC: daniel_megert, dror.banin, markus.kell.r, satyam.kandula, srikanth_sankaran, stephan.herrmann
Version: 3.8   
Target Milestone: 4.3 M1   
Hardware: PC   
OS: Windows 7   
Whiteboard:
Attachments:
Description Flags
proposed fix v1.0 + regression tests none

Description Alexander Weickmann CLA 2012-03-27 09:09:04 EDT
Build Identifier: 20110916-0149

The following compile options cannot be set using the batch compiler:

- org.eclipse.jdt.core.compiler.problem.missingJavadocTagsOverriding
- org.eclipse.jdt.core.compiler.problem.missingJavadocTagsVisibility
- org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionExemptExceptionAndThrowable
- org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionIncludeDocCommentReference
- org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionWhenOverriding
- org.eclipse.jdt.core.compiler.problem.unusedParameterIncludeDocCommentReference
- org.eclipse.jdt.core.compiler.problem.unusedParameterWhenImplementingAbstract
- org.eclipse.jdt.core.compiler.problem.unusedParameterWhenOverridingConcrete
- org.eclipse.jdt.core.compiler.problem.unusedWarningToken

org.eclipse.jdt.internal.compiler.batch.Main#handleErrorOrWarningToken(String, boolean, int) only handles:
- OPTION_ReportInvalidJavadoc
- OPTION_ReportMissingJavadocTags
- OPTION_ReportMissingJavadocComments

As we use a Maven build process, we would like to set our server using the same compiler options as the IDE does.

Reproducible: Always
Comment 1 Satyam Kandula CLA 2012-03-28 07:27:18 EDT
Ayush, Can you take care of this?
Comment 2 Markus Keller CLA 2012-04-17 09:08:46 EDT
In 3.8, more options were added to JavaCore that cannot be controlled individually in the batch compiler ("null", "resource", bug 374605).

In the old days, all options were configurable in the batch compiler as well. In addition, the batch compiler supported a few macro tokens that configured multiple options at once. These were marked in task-using_batch_compiler.htm as "macro for <controlledOptionsList>".


(In reply to comment #0)
> As we use a Maven build process, we would like to set our server using the same
> compiler options as the IDE does.

Since 3.6, the batch compiler supports the option -properties <file>, where you can e.g. pass a .settings/org.eclipse.jdt.core.prefs file:
http://help.eclipse.org/indigo/topic/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm
Comment 3 Jan Sievers CLA 2012-04-17 17:29:34 EDT
*** Bug 371901 has been marked as a duplicate of this bug. ***
Comment 4 Alexander Weickmann CLA 2012-05-15 09:27:44 EDT
Well, we tried it using following Maven Tycho configuration:

<compilerArgument>-properties .settings/org.eclipse.jdt.core.prefs</compilerArgument>

Did not work. There's no error, but he does not recognize the warnings settings. In our project, we've come to the point where we can no longer invest time into this issue.
Comment 5 Ayushman Jain CLA 2012-05-15 10:46:03 EDT
(In reply to comment #4)
> Well, we tried it using following Maven Tycho configuration:
> 
> <compilerArgument>-properties
> .settings/org.eclipse.jdt.core.prefs</compilerArgument>
> 
> Did not work. There's no error, but he does not recognize the warnings
> settings. In our project, we've come to the point where we can no longer invest
> time into this issue.

I will try to accomodate atleast the options you mentioned in comment 0, and if the changes are minimal we can release in time for Juno.
Comment 6 Ayushman Jain CLA 2012-05-16 14:25:57 EDT
Created attachment 215728 [details]
proposed fix v1.0 + regression tests

I've added all of the warnings listed in comment 0 and some more aligned ones.
Comment 7 Srikanth Sankaran CLA 2012-05-17 01:34:28 EDT
(In reply to comment #6)
> Created attachment 215728 [details]
> proposed fix v1.0 + regression tests
> 
> I've added all of the warnings listed in comment 0 and some more aligned ones.

This patch looks a bit too big for ready & routine inclusion in RC2. I think
we should check why the method Markus outlines in comment#2 does not work 
(as claimed in comment#4)

Either there is an operator error - in which case the problem is solved
by clarifying what is wrong in the usage documented in comment#4 - or that
machinery is broken - in which we should look to fix it and enable users
to use the more general way for the rime being.

Ayush, can you see if the  batch compiler option  -properties <file>
allows you to enable these behaviors for which an explicit token is
missing at the moment and if not why not ?
Comment 8 Ayushman Jain CLA 2012-05-17 02:13:17 EDT
(In reply to comment #4)
> Well, we tried it using following Maven Tycho configuration:
> 
> <compilerArgument>-properties
> .settings/org.eclipse.jdt.core.prefs</compilerArgument>
> 
> Did not work. There's no error, but he does not recognize the warnings
> settings. In our project, we've come to the point where we can no longer invest
> time into this issue.

Alexander, can you please check why the .prefs file is not recognized? It seems to work for me. Can you try using the complete path of the .prefs file here? $Project_path/.settings/....prefs
(Every project has a separate .prefs file)
Comment 9 Srikanth Sankaran CLA 2012-05-17 02:19:38 EDT
(In reply to comment #8)

> Alexander, can you please check why the .prefs file is not recognized? It seems
> to work for me. 

Thanks for checking this. I assume you tried to enable some behaviors
for which explicit token don't exist at the moment. If the reporter
confirms the solution works for him, then we can move the more general
fix to 4.3 M1.
Comment 10 Alexander Weickmann CLA 2012-06-03 15:14:55 EDT
Well, -properties works when using the batch compiler. When using Tycho with the -properties option I get following console output:
[DEBUG] Original compiler output: Unrecognized option : -properties "/media/ssd/multi-x-processor/workspace/myproject/.settings/org.eclipse.jdt.core.prefs"
Comment 11 Satyam Kandula CLA 2012-06-06 05:34:32 EDT
(In reply to comment #10)
> Well, -properties works when using the batch compiler. When using Tycho with
> the -properties option I get following console output:
> [DEBUG] Original compiler output: Unrecognized option : -properties
> "/media/ssd/multi-x-processor/workspace/myproject/.settings/org.eclipse.jdt.core.prefs"

Can you please try to add the following in your pom.xml?
 <compilerArguments>
     <properties>/media/ssd/multi-x-processor/workspace/myproject/.settings/org.eclipse.jdt.core.prefs</properties>
 </compilerArguments>
Comment 12 Alexander Weickmann CLA 2012-06-06 15:38:39 EDT
Thank you, Satyam Kandula, your suggested solution is actually really working :-) Big step into the right direction.

But does the batch compiler recognize the newer settings using this method, even though they cannot be specified using -warn? It does not seem so as I am getting "unused import" warnings, even tough the import is required for JavaDocs @link tags ...
Comment 13 Satyam Kandula CLA 2012-06-07 10:37:09 EDT
(In reply to comment #12)
> Thank you, Satyam Kandula, your suggested solution is actually really working
> :-) Big step into the right direction.
> 
> But does the batch compiler recognize the newer settings using this method,
> even though they cannot be specified using -warn? It does not seem so as I am
> getting "unused import" warnings, even tough the import is required for
> JavaDocs @link tags ...

You are right. We are not honoring the 'enable javadoc comment' setting. Only properties starting with the name 'org.eclipse.jdt.core.compiler.problem' are being added and this is not. We probably should handle that separately. I will file a separate bug for it. 

For now, I believe you could do the following
<compilerArgument>-warn:+javadoc</compilerArgument>
<compilerArguments> <properties>C:\Users\IBM_ADMIN\tycho\minerva\org.aniszczyk.minerva.core\.settings\org.eclipse.jdt.core.prefs</properties>
</compilerArguments>
Comment 14 Satyam Kandula CLA 2012-06-07 10:56:19 EDT
(In reply to comment #13)

> You are right. We are not honoring the 'enable javadoc comment' setting. Only
> properties starting with the name 'org.eclipse.jdt.core.compiler.problem' are
> being added and this is not. We probably should handle that separately. I will
> file a separate bug for it. 
Filed bug 382012 to take care of this.
Comment 15 Alexander Weickmann CLA 2012-06-12 07:47:16 EDT
The proposed workaround is not working for us. We do not have all JavaDoc switches enabled, so <compilerArgument>-warn:+javadoc</compilerArgument> yields more warnings than we want. Seems we have to wait for a bugfix.
Comment 16 Ayushman Jain CLA 2012-06-12 08:23:30 EDT
(In reply to comment #15)
> The proposed workaround is not working for us. We do not have all JavaDoc
> switches enabled, so <compilerArgument>-warn:+javadoc</compilerArgument> yields
> more warnings than we want. Seems we have to wait for a bugfix.

I think the right option here should be -enableJavadoc instead of -warn:+javadoc. Satyam, correct me if I'm wrong. Thanks.
Comment 17 Alexander Weickmann CLA 2012-07-12 11:33:56 EDT
(In reply to comment #16)
> (In reply to comment #15)
> > The proposed workaround is not working for us. We do not have all JavaDoc
> > switches enabled, so <compilerArgument>-warn:+javadoc</compilerArgument> yields
> > more warnings than we want. Seems we have to wait for a bugfix.
> 
> I think the right option here should be -enableJavadoc instead of
> -warn:+javadoc. Satyam, correct me if I'm wrong. Thanks.

Thanks, this workaround is actually working :-)
Comment 18 Ayushman Jain CLA 2012-07-19 14:47:12 EDT
Released new batch compiler options into master (Gerrit) via commit 22622fb4f97d8218a8b46b7612c7415d2a54a73e.

Released user doc via http://git.eclipse.org/c/platform/eclipse.platform.common.git/commit/?id=6d6bec52481c50440e047ac3c3df74a7877a5f6a

New options are listed below:
\      invalidJavadoc       all warnings for malformed javadoc tags\n\
\      invalidJavadocTag    validate javadoc tag arguments\n\
\      invalidJavadocTagDep validate deprecated references in javadoc tag args\n\
\      invalidJavadocTagNotVisible  validate non-visible references in javadoc\n\
\							tag args\n\
\      invalidJavadocVisibility(<visibility>)  specify visibility modifier\n\
\					for malformed javadoc tag warnings\n\
\      missingJavadocTags   missing Javadoc tags\n\
\      missingJavadocTagsOverriding missing Javadoc tags in overriding methods\n\
\      missingJavadocTagsMethod missing Javadoc tags for method type parameter\n\
\      missingJavadocTagsVisibility(<visibility>)  specify visibility modifier\n\
\							for missing javadoc tags warnings\n\
\      missingJavadocComments   missing Javadoc comments\n\
\      missingJavadocCommentsOverriding   missing Javadoc tags in overriding\n\
\							methods\n\
\      missingJavadocCommentsVisibility(<visibility>)  specify visibility\n\
\			modifier for missing javadoc comments warnings\n\
\      nullAnnotConflict    conflict between null annotation specified\n\
\			and nullness inferred. Is effective only with\n\
\			nullAnnot option enabled.\n\
\      nullAnnotRedundant   redundant specification of null annotation. Is\n\
\			effective only with nullAnnot option enabled.\n\
\      nullUncheckedConversion unchecked conversion from non-annotated type\n\
\			 to @NonNull type. Is effective only with\n\
\		         nullAnnot option enabled.\n\
\      unusedParam		    unused parameter\n\
\      unusedParamOverriding unused parameter for overriding method\n\
\      unusedParamImplementing unused parameter for implementing method\n\
\      unusedParamIncludeDoc unused parameter documented in comment tag\n\
\      unusedThrownWhenOverriding unused declared thrown exception in \n\
\							overriding method\n\
\      unusedThrownIncludeDocComment     unused declared thrown exception,\n\
\					documented in a comment tag\n\
\      unusedThrownExemptExceptionThrowable  unused declared thrown exception,\n\
\				exempt Exception and Throwable\n\
Comment 19 dror banin CLA 2012-07-23 02:46:43 EDT
Hi guys,
I also trying to set compiler's prefs with 
<compilerArgument>-properties  .settings/org.eclipse.jdt.core.prefs</compilerArgument> option, and it doesn't work :(

Somebody can please attach an example that actually working?

Thanks, Dror.
Comment 20 Ayushman Jain CLA 2012-07-23 03:04:55 EDT
(In reply to comment #19)
> Hi guys,
> I also trying to set compiler's prefs with 
> <compilerArgument>-properties 
> .settings/org.eclipse.jdt.core.prefs</compilerArgument> option, and it doesn't
> work :(
> 
> Somebody can please attach an example that actually working?
> 
> Thanks, Dror.

You need to specify the complete path for the .prefs file. Please see comment 11, comment 13 and others for usage examples.
Comment 21 Alexander Weickmann CLA 2012-07-23 03:07:24 EDT
Here's what works for me:

<!-- Compiler warnings and errors configuration -->
			<plugin>
				<groupId>org.eclipse.tycho</groupId>
				<artifactId>tycho-compiler-plugin</artifactId>
				<version>${tycho-version}</version>
				<configuration>
					<!-- enableJavadoc is necessary until https://bugs.eclipse.org/bugs/show_bug.cgi?id=375366 is fixed -->
					<compilerArgument>-enableJavadoc</compilerArgument>
					<compilerArguments>
						<properties>${project.basedir}/.settings/org.eclipse.jdt.core.prefs</properties>
					</compilerArguments>
				</configuration>
			</plugin>
Comment 22 dror banin CLA 2012-07-23 06:48:45 EDT
Hi,
still donwt work :(
this is my code:

<plugin>
	<groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-compiler-plugin</artifactId>
        <version>0.15.0</version>
        <configuration>
				<properties>C:/ASM_DEV/mvnPrj/helloWorldApp/.settings/org.eclipse.jdt.core.prefs</properties> 
	
        </configuration>
</plugin>

you have any idea?
Comment 23 Ayushman Jain CLA 2012-07-23 06:53:57 EDT
(In reply to comment #22)
> Hi,
> still donwt work :(
> this is my code:
> 
> <plugin>
>     <groupId>org.eclipse.tycho</groupId>
>         <artifactId>tycho-compiler-plugin</artifactId>
>         <version>0.15.0</version>
>         <configuration>
>                
> <properties>C:/ASM_DEV/mvnPrj/helloWorldApp/.settings/org.eclipse.jdt.core.prefs</properties> 
> 
>         </configuration>
> </plugin>
> 
> you have any idea?

Yes, I think someone ate your <compilerArgument> tag. ;)
Also, are you using Tycho? Alexander's usage may not work verbatim for you, according to whether or not you're using Tycho.
Comment 24 dror banin CLA 2012-07-23 07:05:56 EDT
i added tag and still don't work..
i change Tycho to  like this:

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>2.3.2</version>
	<configuration>
	<compilerId>eclipse</compilerId>
					<compilerArguments>
						<properties>C:/ASM_DEV/mvnPrj/helloWorldApp/.settings/org.eclipse.jdt.core.prefs</properties>
					</compilerArguments>
				</configuration>
			</plugin>
Comment 25 dror banin CLA 2012-07-23 07:12:51 EDT
I added <compilerArguments> tag and still don't work..
Then i change Tycho to org.apache.maven.plugins like this:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>2.3.2</version>
    <configuration>
	<compilerId>eclipse</compilerId>
	<compilerArguments>
						<properties>C:/ASM_DEV/mvnPrj/helloWorldApp/.settings/org.eclipse.jdt.core.prefs</properties>
	
        </compilerArguments>
    </configuration>
</plugin>

and nothing.. :(
Comment 26 Srikanth Sankaran CLA 2012-08-07 01:11:27 EDT
@Ayush, do you have any recommendations for comment#24 & comment#25 ?

Verified for 4.3 M1 using build I20120805-2000
Comment 27 Ayushman Jain CLA 2012-08-08 09:21:55 EDT
(In reply to comment #26)
> @Ayush, do you have any recommendations for comment#24 & comment#25 ?

I don't know how Tycho works so not sure what can be the issue here.
Comment 28 Stephan Herrmann CLA 2012-08-15 18:29:13 EDT
After some more research on Tycho I see two different modes of usage:

When building Eclipse plug-ins etc the following pattern is used:

<packaging>eclipse-plugin</packaging>
<build>
	<plugins>
		<plugin>
			<groupId>org.eclipse.tycho</groupId>
			<artifactId>tycho-maven-plugin</artifactId>
			<version>${tycho.version}</version>
			<extensions>true</extensions>
		</plugin>
		<plugin>
			<groupId>org.eclipse.tycho</groupId>
			<artifactId>tycho-compiler-plugin</artifactId>
			<version>${tycho.version}</version>
			<configuration>
				<source>1.7</source>
				<target>1.7</target>
				<compilerArguments>
					<properties>${project.basedir}/.settings/org.eclipse.jdt.core.prefs</properties>
				</compilerArguments>
			</configuration>
		</plugin>
	</plugins>
</build>

when using Tycho to configure regular maven projects to use the JDT compiler this pattern applies:

<packaging>jar</packaging>
<build>
	<plugins>
		<plugin>
			<artifactId>maven-compiler-plugin</artifactId>
			<configuration>
				<source>1.7</source>
				<target>1.7</target>
				<compilerId>jdt</compilerId>
				<compilerArguments>
					<properties>${project.basedir}/.settings/org.eclipse.jdt.core.prefs</properties>
				</compilerArguments>
			</configuration>
			<dependencies>
				<dependency>
					<groupId>org.eclipse.tycho</groupId>
					<artifactId>tycho-compiler-jdt</artifactId>
					<version>${tycho.version}</version>
				</dependency>
			</dependencies>
		</plugin>
	</plugins>
</build>

For me both variants work for using the store per-project compiler preferences.

@Dror, can you please check which variant should apply for you and report if you get it to work now?