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 all commits
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
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
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
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,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
Open in desktop
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
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