protoc-generated Java files generate lots of warnings with Java 8 javadoc #304

huxi · 2015-04-26T15:20:36Z

warning: no @return
warning: no @param for value
warning: no @param for index
warning: no @param for builderForValue

See also Turning off doclint in JDK 8 Javadoc for a workaround.

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

gliptak · 2015-06-16T23:39:24Z

Could the compiler generate the Javadoc tags?

huxi · 2015-06-16T23:46:29Z

There are some options:

it could generate stupid comments like @param value the value
it could not generate any of those comments at all
it could generate the current comments, but starting with /* instead of /** - so they are not real javadoc comments.

I'd go for either 1. or 3.

gliptak · 2015-06-17T01:45:06Z

The compiler probably has "knowledge" what all the parameters are (as it generates a patterned set of accessor methods).

The javadoc linter in Java 8 produces a larger number of warnings that are not easily fixable for us since they depend on upstream fixes, see e.g. protocolbuffers/protobuf#304 So just run without the linter for now.

@inheritdoc

* Exclude v1 API from javadoc generation I think it's best to skip this set since the V1 API is deprecated (and it generates a bunch of warnings). We can always change our minds later of course if we have to revisit this. Testing Done: - verified that the warnings produced during javadoc:javadoc for v1 protos go away * Remove executable permissions from README.md No need for +x on this markdown file. * Autofix a large number of javadoc warnings This change is the result of using javadoc:fix to mostly automatically fix a huge set of javadoc warnings. There were a couple of cases where I had to fix up what the autofixer produced: BigtableOptions.java - for some reason the autofixer inserted copies of a large number of functions and members resulting in duplicated / redefined names and a non-compiling file. Fixed it manually after inspecting the damage. BulkOptions.java - tool didn't know to change '<' to '<' and so generated bad HTML. author tags: The tool inserted @author dharan all over the place and I manually changed it to sduskis since that seemed like the logical default. Testing Done: - mvn javadoc:javadoc (still produces warnings, but less of them now) - mvn clean install (all tests pass) * Silence the javadoc linter The javadoc linter in Java 8 produces a larger number of warnings that are not easily fixable for us since they depend on upstream fixes, see e.g. protocolbuffers/protobuf#304 So just run without the linter for now. * Fix remaining javadoc warnings - fix a couple of warnings for @link cases that javadoc was unable to resolve, and add a link to the gRPC docs and make sure io.grpc.Status.Code can be resolved - Remove autofixer's mistakenly applied @inheritdoc - fixup documentation for Logger class to better explain varargs use

@bertholdreinwald

This experimental interface is called Caffe2DML and doesnot affect other functionality. - Updated the interface to match the Caffe specification as per @bertholdreinwald 's suggestion. - Added support for fine-tuning. - Added support for explain, statistics and gpu. Closes #422.

liujisi · 2017-12-11T20:54:01Z

We are closing open issues. Feel free to send PRs and reopen if you'd like to follow up on the issue.

ST-DDT · 2018-09-13T14:04:43Z

Is that issue fixed yet? AFAICT it isn't in com.google.protobuf:protoc:3.6.1.

I tested it in my maven project with a config similar to this one.

<build>
	<extensions>
		<extension>
			<groupId>kr.motd.maven</groupId>
			<artifactId>os-maven-plugin</artifactId>
			<version>1.6.0</version>
		</extension>
	</extensions>

	<plugins>
		<plugin>
			<groupId>org.xolstice.maven.plugins</groupId>
			<artifactId>protobuf-maven-plugin</artifactId>
			<version>0.5.1</version>
			<configuration>
				<clearOutputDirectory>false</clearOutputDirectory>
				<protocArtifact>com.google.protobuf:protoc:3.6.1:exe:${os.detected.classifier}</protocArtifact>
			</configuration>
			<executions>
				<execution>
					<phase>generate-sources</phase>
					<goals>
						<goal>compile</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
		<plugin>
			<artifactId>maven-javadoc-plugin</artifactId>
			<executions>
				<execution>
					<id>attach-javadoc</id>
					<goals>
						<goal>jar</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

which generates classes with methods like these:

  /**
   * <code>repeated string tag = 3;</code>
   */
  java.util.List<java.lang.String>
      getTagList();
  /**
   * <code>repeated string tag = 3;</code>
   */
  int getTagCount();
  /**
   * <code>repeated string tag = 3;</code>
   */
  java.lang.String getTag(int index);
  /**
   * <code>repeated string tag = 3;</code>
   */
  com.google.protobuf.ByteString
      getTagBytes(int index);

and causes warnings like these:

[WARNING] public Builder setTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:666: warning: no @param for value
[WARNING] public Builder setTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:666: warning: no @return
[WARNING] public Builder setTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:679: warning: no @param for value
[WARNING] public Builder addTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:679: warning: no @return
[WARNING] public Builder addTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:692: warning: no @param for values
[WARNING] public Builder addAllTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:692: warning: no @return
[WARNING] public Builder addAllTag(
[WARNING] ^
[WARNING] [...]/SampleProto.java:703: warning: no @return
[WARNING] public Builder clearTag() {
[WARNING] ^
[WARNING] [...]/SampleProto.java:712: warning: no @param for value
[WARNING] public Builder addTagBytes(
[WARNING] ^
[WARNING] [...]/SampleProto.java:712: warning: no @return
[WARNING] public Builder addTagBytes(
[WARNING] ^

vmsh0 · 2019-12-13T20:45:33Z

+1 I would like to see this fixed, either by having informative documentation generated or by having dummy tags added.

ST-DDT · 2019-12-13T23:36:27Z

I recently started with the second batch of javadoc additions, but there are plenty of different cases.

getFieldOrBuilder, getFieldBuilder, getRepeatedFieldOrBuilderAtIndex, getRepeatedFieldBuilderAtIndex, addRepeatedFieldBuilder, addRepeatedFieldBuilderAtIndex

and these are just a few of them that return a Builder or an XOrBuilder.
Maybe I can do the "simple" ones in the next month so we get less warnings for the start.

xfxyjwf added java cleanup labels Jan 20, 2016

gerben-s assigned liujisi Mar 9, 2017

alexanderkjall mentioned this issue Apr 12, 2017

Code quality: Address Javadoc warnings google/certificate-transparency-java#7

Closed

niketanpansare mentioned this issue Apr 21, 2017

[SYSTEMML-692] Separated Caffe2dml into a separate jar apache/systemds#466

Closed

liujisi added the to close label Dec 11, 2017

jtattermusch closed this as completed Dec 11, 2017

google-admin unassigned liujisi Aug 21, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

protoc-generated Java files generate lots of warnings with Java 8 javadoc #304

protoc-generated Java files generate lots of warnings with Java 8 javadoc #304

huxi commented Apr 26, 2015

gliptak commented Jun 16, 2015

huxi commented Jun 16, 2015

gliptak commented Jun 17, 2015

liujisi commented Dec 11, 2017

ST-DDT commented Sep 13, 2018

vmsh0 commented Dec 13, 2019

ST-DDT commented Dec 13, 2019

protoc-generated Java files generate lots of warnings with Java 8 javadoc #304

protoc-generated Java files generate lots of warnings with Java 8 javadoc #304

Comments

huxi commented Apr 26, 2015

gliptak commented Jun 16, 2015

huxi commented Jun 16, 2015

gliptak commented Jun 17, 2015

liujisi commented Dec 11, 2017

ST-DDT commented Sep 13, 2018

vmsh0 commented Dec 13, 2019

ST-DDT commented Dec 13, 2019