Draft: Fix javadoc warnings in generated files

pull/6231/head
ST-DDT 6 years ago
parent 6153f80876
commit 6ee16a9c60
No known key found for this signature in database
GPG Key ID: B0ACEF01F52929C3
  1. 44
      src/google/protobuf/compiler/java/java_doc_comment.cc
  2. 4
      src/google/protobuf/compiler/java/java_doc_comment.h
  3. 2
      src/google/protobuf/compiler/java/java_enum.cc
  4. 2
      src/google/protobuf/compiler/java/java_enum_lite.cc
  5. 2
      src/google/protobuf/compiler/java/java_message.cc
  6. 32
      src/google/protobuf/compiler/java/java_message_field.cc
  7. 4
      src/google/protobuf/compiler/java/java_message_field_lite.cc
  8. 16
      src/google/protobuf/compiler/java/java_primitive_field.cc
  9. 20
      src/google/protobuf/compiler/java/java_primitive_field_lite.cc
  10. 24
      src/google/protobuf/compiler/java/java_string_field.cc

@ -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);
@ -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) {
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());
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_);

@ -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);

@ -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"

@ -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"

@ -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"

@ -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");
@ -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"
@ -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"
@ -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_,
@ -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)",
@ -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"
@ -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$$}$()",
@ -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"
@ -579,7 +579,7 @@ 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"
@ -587,7 +587,7 @@ void ImmutableMessageOneofFieldGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
// Field getField()
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
PrintNestedBuilderFunction(
printer, "$deprecation$public $type$ ${$get$capitalized_name$$}$()",

@ -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");
}

@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"

@ -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");
}
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"
@ -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"

@ -190,14 +190,14 @@ int ImmutableStringFieldGenerator::GetNumBitsForBuilder() const {
void ImmutableStringFieldGenerator::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$java.lang.String get$capitalized_name$();\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$com.google.protobuf.ByteString\n"
" get$capitalized_name$Bytes();\n");
@ -209,7 +209,7 @@ void ImmutableStringFieldGenerator::GenerateMembers(
PrintExtraFieldInfo(variables_, printer);
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
@ -218,7 +218,7 @@ void ImmutableStringFieldGenerator::GenerateMembers(
printer->Annotate("{", "}", descriptor_);
}
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public java.lang.String ${$get$capitalized_name$$}$() {\n"
@ -242,7 +242,7 @@ void ImmutableStringFieldGenerator::GenerateMembers(
" return s;\n"
" }\n"
"}\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public com.google.protobuf.ByteString\n"
" ${$get$capitalized_name$Bytes$}$() {\n"
@ -265,7 +265,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
printer->Print(variables_,
"private java.lang.Object $name$_ $default_init$;\n");
if (SupportFieldPresence(descriptor_->file())) {
WriteFieldDocComment(printer, descriptor_);
WriteFieldHaserDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public boolean ${$has$capitalized_name$$}$() {\n"
@ -274,7 +274,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
printer->Annotate("{", "}", descriptor_);
}
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public java.lang.String ${$get$capitalized_name$$}$() {\n"
@ -299,7 +299,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
" }\n"
"}\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldGetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public com.google.protobuf.ByteString\n"
" ${$get$capitalized_name$Bytes$}$() {\n"
@ -316,7 +316,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
"}\n");
printer->Annotate("{", "}", descriptor_);
WriteFieldDocComment(printer, descriptor_);
WriteFieldSetterDocComment(printer, descriptor_);
printer->Print(variables_,
"$deprecation$public Builder ${$set$capitalized_name$$}$(\n"
" java.lang.String value) {\n"
@ -327,7 +327,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
" return this;\n"
"}\n");
printer->Annotate("{", "}", descriptor_);
WriteFieldDocComment(printer, descriptor_);
WriteFieldClearerDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public Builder ${$clear$capitalized_name$$}$() {\n"
@ -342,7 +342,7 @@ void ImmutableStringFieldGenerator::GenerateBuilderMembers(
" return this;\n"
"}\n");
WriteFieldDocComment(printer, descriptor_);
WriteFieldSetterDocComment(printer, descriptor_);
printer->Print(
variables_,
"$deprecation$public Builder ${$set$capitalized_name$Bytes$}$(\n"

Loading…
Cancel
Save