Skip to content

Commit

Permalink
Merge pull request #6231 from ST-DDT/fix-javadoc-warnings
Browse files Browse the repository at this point in the history 
Fix javadoc warnings in generated files
  • Loading branch information
Hao Nguyen committed Jun 27, 2019
2 parents de5a1fa + 351a7cd commit f30c68b
Show file tree
Hide file tree
Showing 14 changed files with 551 additions and 267 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Expand Up @@ -197,6 +197,9 @@ cmake/cmake-build-debug/
# Visual Studio 2017
.vs

# Visual Studio Code
/.vscode/

# IntelliJ
.idea
*.iml
179 changes: 174 additions & 5 deletions src/google/protobuf/compiler/java/java_doc_comment.cc
View file
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,178 @@ void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field) {
printer->Print(" */\n");
}

void WriteFieldAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
switch (type) {
case HAZZER:
printer->Print(" * @return Whether the $name$ field is set.\n", "name",
field->camelcase_name());
break;
case GETTER:
printer->Print(" * @return The $name$.\n", "name",
field->camelcase_name());
break;
case SETTER:
printer->Print(" * @param value The $name$ to set.\n", "name",
field->camelcase_name());
break;
case CLEARER:
// Print nothing
break;
// Repeated
case LIST_COUNT:
printer->Print(" * @return The number of $name$(s).\n", "name",
field->camelcase_name());
break;
case LIST_GETTER:
printer->Print(" * @return A list containing the $name$(s).\n", "name",
field->camelcase_name());
break;
case LIST_INDEXED_GETTER:
printer->Print(" * @param index The index of the element to return.\n");
printer->Print(" * @return The $name$(s) at the given index.\n", "name",
field->camelcase_name());
break;
case LIST_INDEXED_SETTER:
printer->Print(" * @param index The index to set the value at.\n");
printer->Print(" * @param value The $name$ to set.\n", "name",
field->camelcase_name());
break;
case LIST_ADDER:
printer->Print(" * @param value The $name$ to add.\n", "name",
field->camelcase_name());
break;
case LIST_MULTI_ADDER:
printer->Print(" * @param values The $name$(s) to add.\n", "name",
field->camelcase_name());
break;
}
if (builder) {
printer->Print(" * @return This builder for chaining.\n");
}
printer->Print(" */\n");
}

void WriteFieldEnumValueAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
switch (type) {
case HAZZER:
// Should never happen
break;
case GETTER:
printer->Print(" * @return The enum value for $name$.\n", "name",
field->camelcase_name());
break;
case SETTER:
printer->Print(" * @param value The enum value for $name$ to set.\n",
"name", field->camelcase_name());
break;
case CLEARER:
// Print nothing
break;
// Repeated
case LIST_COUNT:
// Should never happen
break;
case LIST_GETTER:
printer->Print(" * @return A list containing the enum values for "
"$name$(s).\n", "name", field->camelcase_name());
break;
case LIST_INDEXED_GETTER:
printer->Print(" * @param index The index of the value to return.\n");
printer->Print(" * @return The enum value of the $name$ at the given "
"index.\n", "name", field->camelcase_name());
break;
case LIST_INDEXED_SETTER:
printer->Print(" * @param index The index to set the value at.\n");
printer->Print(" * @param value The enum value of the $name$ to set.\n",
"name", field->camelcase_name());
break;
case LIST_ADDER:
printer->Print(" * @param value The enum value of the $name$ to add.\n",
"name", field->camelcase_name());
break;
case LIST_MULTI_ADDER:
printer->Print(" * @param values The enum values of the $name$(s) to "
"add.\n", "name", field->camelcase_name());
break;
}
if (builder) {
printer->Print(" * @return This builder for chaining.\n");
}
printer->Print(" */\n");
}

void WriteFieldStringBytesAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder) {
printer->Print("/**\n");
WriteDocCommentBody(printer, field);
printer->Print(" * <code>$def$</code>\n", "def",
EscapeJavadoc(FirstLineOf(field->DebugString())));
switch (type) {
case HAZZER:
// Should never happen
break;
case GETTER:
printer->Print(" * @return The bytes for $name$.\n", "name",
field->camelcase_name());
break;
case SETTER:
printer->Print(" * @param value The bytes for $name$ to set.\n",
"name", field->camelcase_name());
break;
case CLEARER:
// Print nothing
break;
// Repeated
case LIST_COUNT:
// Should never happen
break;
case LIST_GETTER:
printer->Print(" * @return A list containing the bytes for $name$(s).\n",
"name", field->camelcase_name());
break;
case LIST_INDEXED_GETTER:
printer->Print(" * @param index The index of the value to return.\n");
printer->Print(" * @return The bytes of the $name$ at the given index.\n",
"name", field->camelcase_name());
break;
case LIST_INDEXED_SETTER:
printer->Print(" * @param index The index to set the value at.\n");
printer->Print(" * @param value The bytes of the $name$ to set.\n",
"name", field->camelcase_name());
break;
case LIST_ADDER:
printer->Print(" * @param value The bytes of the $name$ to add.\n",
"name", field->camelcase_name());
break;
case LIST_MULTI_ADDER:
printer->Print(" * @param values The bytes of the $name$(s) to add.\n",
"name", field->camelcase_name());
break;
}
if (builder) {
printer->Print(" * @return This builder for chaining.\n");
}
printer->Print(" */\n");
}

// Enum

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

enum FieldAccessorType {

HAZZER,
GETTER,
SETTER,
CLEARER,
// Repeated
LIST_COUNT,
LIST_GETTER,
LIST_INDEXED_GETTER,
LIST_INDEXED_SETTER,
LIST_ADDER,
LIST_MULTI_ADDER

};

void WriteMessageDocComment(io::Printer* printer, const Descriptor* message);
void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field);
void WriteFieldAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder = false);
void WriteFieldEnumValueAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder = false);
void WriteFieldStringBytesAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
const bool builder = false);
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
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

0 comments on commit f30c68b

Please sign in to comment.