Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix javadoc warnings in generated files #6231

Merged
4 commits merged into from Jun 27, 2019
Merged

Fix javadoc warnings in generated files #6231

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6ee16a9
Draft: Fix javadoc warnings in generated files
ST-DDT Jun 8, 2019
73e0d74
Switch to using enum based methods
ST-DDT Jun 15, 2019
5af81a4
Use parameter name comment
ST-DDT Jun 26, 2019
351a7cd
Follow line length guidelines
ST-DDT Jun 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
44 changes: 39 additions & 5 deletions src/google/protobuf/compiler/java/java_doc_comment.cc
View file
Open in desktop
Expand Up @@ -173,13 +173,10 @@ void WriteMessageDocComment(io::Printer* printer, const Descriptor* message) {
}

void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field) {
// In theory we should have slightly different comments for setters, getters,
// etc., but in practice everyone already knows the difference between these
// so it's redundant information.

// We start the comment with the main body based on the comments from the
// .proto file (if present). We then end with the field declaration, e.g.:
// .proto file (if present). We then continue with the field declaration, e.g.:
// optional string foo = 5;
// And then we end with the javadoc tags if applicable.
// If the field is a group, the debug string might end with {.
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
Expand All @@ -188,6 +185,43 @@ void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field) {
printer->Print(" */\n");
}

void WriteFieldGetterDocComment(io::Printer* printer, const FieldDescriptor* field) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
printer->Print(" * @return The $name$.\n", "name", field->camelcase_name());
printer->Print(" */\n");
}

void WriteFieldHaserDocComment(io::Printer* printer, const FieldDescriptor* field) {
ST-DDT marked this conversation as resolved.
Show resolved Hide resolved
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
printer->Print(" * @return Whether the $name$ field is set.\n", "name", field->camelcase_name());
ST-DDT marked this conversation as resolved.
Show resolved Hide resolved
printer->Print(" */\n");
}

void WriteFieldSetterDocComment(io::Printer* printer, const FieldDescriptor* field) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
printer->Print(" * @param value The $name$ to set.\n", "name", field->camelcase_name());
printer->Print(" * @return This builder for chaining.\n");
printer->Print(" */\n");
}

void WriteFieldClearerDocComment(io::Printer* printer, const FieldDescriptor* field) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
printer->Print(" * @return This builder for chaining.\n");
printer->Print(" */\n");
}

void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_) {
printer->Print("/**\n");
WriteDocCommentBody(printer, enum_);
Expand Down
4 changes: 4 additions & 0 deletions src/google/protobuf/compiler/java/java_doc_comment.h
View file
Open in desktop
Expand Up @@ -54,6 +54,10 @@ namespace java {

void WriteMessageDocComment(io::Printer* printer, const Descriptor* message);
void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteFieldGetterDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteFieldHaserDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteFieldSetterDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteFieldClearerDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_);
void WriteEnumValueDocComment(io::Printer* printer,
const EnumValueDescriptor* value);
Expand Down
2 changes: 2 additions & 0 deletions src/google/protobuf/compiler/java/java_enum.cc
View file
Open in desktop
Expand Up @@ -175,6 +175,8 @@ void EnumGenerator::Generate(io::Printer* printer) {
"}\n"
"\n"
"/**\n"
" * @param value The number of the enum to look for.\n"
" * @return The enum associated with the given number.\n"
" * @deprecated Use {@link #forNumber(int)} instead.\n"
" */\n"
"@java.lang.Deprecated\n"
Expand Down
2 changes: 2 additions & 0 deletions src/google/protobuf/compiler/java/java_enum_lite.cc
View file
Open in desktop
Expand Up @@ -150,6 +150,8 @@ void EnumLiteGenerator::Generate(io::Printer* printer) {
"}\n"
"\n"
"/**\n"
" * @param value The number of the enum to look for.\n"
" * @return The enum associated with the given number.\n"
" * @deprecated Use {@link #forNumber(int)} instead.\n"
" */\n"
"@java.lang.Deprecated\n"
Expand Down
2 changes: 2 additions & 0 deletions src/google/protobuf/compiler/java/java_message.cc
View file
Open in desktop
Expand Up @@ -439,6 +439,8 @@ void ImmutableMessageGenerator::Generate(io::Printer* printer) {
printer->Print(
vars,
"/**\n"
" * @param value The number of the enum to look for.\n"
" * @return The enum associated with the given number.\n"
" * @deprecated Use {@link #forNumber(int)} instead.\n"
" */\n"
"@java.lang.Deprecated\n"
Expand Down
32 changes: 16 additions & 16 deletions src/google/protobuf/compiler/java/java_message_field.cc
View file
Open in desktop
Expand Up @@ -144,12 +144,12 @@ void ImmutableMessageFieldGenerator::GenerateInterfaceMembers(
// interface so that builders can choose dynamically to either return a
// message or a nested builder, so that asking for the interface doesn't
// cause a message to ever be built.
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(variables_, "$deprecation$boolean has$capitalized_name$();\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_, "$deprecation$$type$ get$capitalized_name$();\n");

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$$type$OrBuilder get$capitalized_name$OrBuilder();\n");
Expand All @@ -161,14 +161,14 @@ void ImmutableMessageFieldGenerator::GenerateMembers(
PrintExtraFieldInfo(variables_, printer);

if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
" return $get_has_field_bit_message$;\n"
"}\n");
printer->Annotate("{", "}", descriptor_);
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand All @@ -185,14 +185,14 @@ void ImmutableMessageFieldGenerator::GenerateMembers(
"}\n");
printer->Annotate("{", "}", descriptor_);
} else {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
" return $name$_ != null;\n"
"}\n");
printer->Annotate("{", "}", descriptor_);
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand Down Expand Up @@ -261,7 +261,7 @@ void ImmutableMessageFieldGenerator::GenerateBuilderMembers(
// field of type "Field" called "Field".

// boolean hasField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
if (support_field_presence) {
printer->Print(
variables_,
Expand All @@ -279,14 +279,14 @@ void ImmutableMessageFieldGenerator::GenerateBuilderMembers(
}

// Field getField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer, "$deprecation$public $type$ ${$get$capitalized_name$$}$()",
"return $name$_ == null ? $type$.getDefaultInstance() : $name$_;\n",
"return $name$Builder_.getMessage();\n", NULL);

// Field.Builder setField(Field value)
WriteFieldDocComment(printer, descriptor_);
WriteFieldSetterDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer,
"$deprecation$public Builder ${$set$capitalized_name$$}$($type$ value)",
Expand All @@ -303,7 +303,7 @@ void ImmutableMessageFieldGenerator::GenerateBuilderMembers(
"return this;\n");

// Field.Builder setField(Field.Builder builderForValue)
WriteFieldDocComment(printer, descriptor_);
WriteFieldSetterDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer,
"$deprecation$public Builder ${$set$capitalized_name$$}$(\n"
Expand Down Expand Up @@ -347,7 +347,7 @@ void ImmutableMessageFieldGenerator::GenerateBuilderMembers(
"return this;\n");

// Field.Builder clearField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldClearerDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer, "$deprecation$public Builder ${$clear$capitalized_name$$}$()",

Expand Down Expand Up @@ -535,13 +535,13 @@ ImmutableMessageOneofFieldGenerator::~ImmutableMessageOneofFieldGenerator() {}
void ImmutableMessageOneofFieldGenerator::GenerateMembers(
io::Printer* printer) const {
PrintExtraFieldInfo(variables_, printer);
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
" return $has_oneof_case_message$;\n"
"}\n");
printer->Annotate("{", "}", descriptor_);
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
" if ($has_oneof_case_message$) {\n"
Expand Down Expand Up @@ -579,15 +579,15 @@ void ImmutableMessageOneofFieldGenerator::GenerateBuilderMembers(
// field of type "Field" called "Field".

// boolean hasField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
" return $has_oneof_case_message$;\n"
"}\n");
printer->Annotate("{", "}", descriptor_);

// Field getField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer, "$deprecation$public $type$ ${$get$capitalized_name$$}$()",

Expand Down
4 changes: 2 additions & 2 deletions src/google/protobuf/compiler/java/java_message_field_lite.cc
View file
Open in desktop
Expand Up @@ -121,9 +121,9 @@ int ImmutableMessageFieldLiteGenerator::GetNumBitsForMessage() const {

void ImmutableMessageFieldLiteGenerator::GenerateInterfaceMembers(
io::Printer* printer) const {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(variables_, "$deprecation$boolean has$capitalized_name$();\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_, "$deprecation$$type$ get$capitalized_name$();\n");
}

Expand Down
16 changes: 8 additions & 8 deletions src/google/protobuf/compiler/java/java_primitive_field.cc
View file
Open in desktop
Expand Up @@ -219,7 +219,7 @@ void ImmutablePrimitiveFieldGenerator::GenerateMembers(
printer->Print(variables_, "private $field_type$ $name$_;\n");
PrintExtraFieldInfo(variables_, printer);
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
Expand All @@ -228,7 +228,7 @@ void ImmutablePrimitiveFieldGenerator::GenerateMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
" return $name$_;\n"
Expand All @@ -241,7 +241,7 @@ void ImmutablePrimitiveFieldGenerator::GenerateBuilderMembers(
printer->Print(variables_, "private $field_type$ $name$_ $default_init$;\n");

if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
Expand All @@ -250,7 +250,7 @@ void ImmutablePrimitiveFieldGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
" return $name$_;\n"
Expand Down Expand Up @@ -492,7 +492,7 @@ void ImmutablePrimitiveOneofFieldGenerator::GenerateMembers(
io::Printer* printer) const {
PrintExtraFieldInfo(variables_, printer);
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
Expand All @@ -501,7 +501,7 @@ void ImmutablePrimitiveOneofFieldGenerator::GenerateMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
" if ($has_oneof_case_message$) {\n"
Expand All @@ -515,7 +515,7 @@ void ImmutablePrimitiveOneofFieldGenerator::GenerateMembers(
void ImmutablePrimitiveOneofFieldGenerator::GenerateBuilderMembers(
io::Printer* printer) const {
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
Expand All @@ -524,7 +524,7 @@ void ImmutablePrimitiveOneofFieldGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
" if ($has_oneof_case_message$) {\n"
Expand Down
20 changes: 10 additions & 10 deletions src/google/protobuf/compiler/java/java_primitive_field_lite.cc
View file
Open in desktop
Expand Up @@ -198,11 +198,11 @@ int ImmutablePrimitiveFieldLiteGenerator::GetNumBitsForMessage() const {
void ImmutablePrimitiveFieldLiteGenerator::GenerateInterfaceMembers(
io::Printer* printer) const {
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$boolean has$capitalized_name$();\n");
}
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_, "$deprecation$$type$ get$capitalized_name$();\n");
}

Expand All @@ -218,7 +218,7 @@ void ImmutablePrimitiveFieldLiteGenerator::GenerateMembers(
printer->Print(variables_, "private $field_type$ $name$_;\n");
PrintExtraFieldInfo(variables_, printer);
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"@java.lang.Override\n"
Expand All @@ -228,7 +228,7 @@ void ImmutablePrimitiveFieldLiteGenerator::GenerateMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"@java.lang.Override\n"
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand Down Expand Up @@ -264,7 +264,7 @@ void ImmutablePrimitiveFieldLiteGenerator::GenerateMembers(
void ImmutablePrimitiveFieldLiteGenerator::GenerateBuilderMembers(
io::Printer* printer) const {
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"@java.lang.Override\n"
Expand All @@ -274,7 +274,7 @@ void ImmutablePrimitiveFieldLiteGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"@java.lang.Override\n"
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand Down Expand Up @@ -347,7 +347,7 @@ void ImmutablePrimitiveOneofFieldLiteGenerator::GenerateMembers(
io::Printer* printer) const {
PrintExtraFieldInfo(variables_, printer);
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"@java.lang.Override\n"
Expand All @@ -357,7 +357,7 @@ void ImmutablePrimitiveOneofFieldLiteGenerator::GenerateMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"@java.lang.Override\n"
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand Down Expand Up @@ -397,7 +397,7 @@ void ImmutablePrimitiveOneofFieldLiteGenerator::GenerateFieldInfo(
void ImmutablePrimitiveOneofFieldLiteGenerator::GenerateBuilderMembers(
io::Printer* printer) const {
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"@java.lang.Override\n"
Expand All @@ -407,7 +407,7 @@ void ImmutablePrimitiveOneofFieldLiteGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
}

WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"@java.lang.Override\n"
"$deprecation$public $type$ ${$get$capitalized_name$$}$() {\n"
Expand Down