Chiebot-Mirror
/
protobuf
mirror of https://github.com/protocolbuffers/protobuf.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Strip nonfunctional Javadoc comments from .proto comments.

Browse Source 
PiperOrigin-RevId: 601267733
pull/15575/head
Sandy Zhang 10 months ago committed by Copybara-Service
parent 9396fe26f0
commit 7f1ef7ea09
9 changed files with 76 additions and 69 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 41
      src/google/protobuf/compiler/java/doc_comment.cc
  2. 38
      src/google/protobuf/compiler/java/doc_comment.h
  3. 10
      src/google/protobuf/compiler/java/enum.cc
  4. 10
      src/google/protobuf/compiler/java/enum_lite.cc
  5. 5
      src/google/protobuf/compiler/java/message.cc
  6. 2
      src/google/protobuf/compiler/java/message_builder.cc
  7. 2
      src/google/protobuf/compiler/java/message_builder_lite.cc
  8. 5
      src/google/protobuf/compiler/java/message_lite.cc
  9. 4
      src/google/protobuf/compiler/java/service.cc

41
src/google/protobuf/compiler/java/doc_comment.cc
Unescape View File

@ -124,6 +124,7 @@ static std::string EscapeKdoc(const std::string& input) {
static void WriteDocCommentBodyForLocation(io::Printer* printer, static void WriteDocCommentBodyForLocation(io::Printer* printer,
const SourceLocation& location, const SourceLocation& location,
const Options options,
const bool kdoc) { const bool kdoc) {
std::string comments = location.leading_comments.empty() std::string comments = location.leading_comments.empty()
? location.trailing_comments ? location.trailing_comments
@ -146,6 +147,9 @@ static void WriteDocCommentBodyForLocation(io::Printer* printer,
printer->Print(" * <pre>\n"); printer->Print(" * <pre>\n");
} }
// TODO: Remove once prototiller can avoid making
// extraneous formatting changes to comments.
if (!options.strip_nonfunctional_codegen) {
for (size_t i = 0; i < lines.size(); i++) { for (size_t i = 0; i < lines.size(); i++) {
// Lines should start with a single space and any extraneous leading // Lines should start with a single space and any extraneous leading
// spaces should be stripped. For lines starting with a /, the leading // spaces should be stripped. For lines starting with a /, the leading
@ -162,6 +166,7 @@ static void WriteDocCommentBodyForLocation(io::Printer* printer,
printer->Print(" *\n"); printer->Print(" *\n");
} }
} }
}
if (kdoc) { if (kdoc) {
printer->Print(" * ```\n"); printer->Print(" * ```\n");
@ -175,10 +180,10 @@ static void WriteDocCommentBodyForLocation(io::Printer* printer,
template <typename DescriptorType> template <typename DescriptorType>
static void WriteDocCommentBody(io::Printer* printer, static void WriteDocCommentBody(io::Printer* printer,
const DescriptorType* descriptor, const DescriptorType* descriptor,
const bool kdoc) { const Options options, const bool kdoc) {
SourceLocation location; SourceLocation location;
if (descriptor->GetSourceLocation(&location)) { if (descriptor->GetSourceLocation(&location)) {
WriteDocCommentBodyForLocation(printer, location, kdoc); WriteDocCommentBodyForLocation(printer, location, options, kdoc);
} }
} }
@ -213,9 +218,9 @@ static void WriteDebugString(io::Printer* printer, const FieldDescriptor* field,
} }
void WriteMessageDocComment(io::Printer* printer, const Descriptor* message, void WriteMessageDocComment(io::Printer* printer, const Descriptor* message,
const bool kdoc) { const Options options, const bool kdoc) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, message, kdoc); WriteDocCommentBody(printer, message, options, kdoc);
if (kdoc) { if (kdoc) {
printer->Print( printer->Print(
" * Protobuf type `$fullname$`\n" " * Protobuf type `$fullname$`\n"
@ -238,7 +243,7 @@ void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field,
// And then we end with the javadoc tags if applicable. // And then we end with the javadoc tags if applicable.
// If the field is a group, the debug string might end with {. // If the field is a group, the debug string might end with {.
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, field, kdoc); WriteDocCommentBody(printer, field, options, kdoc);
WriteDebugString(printer, field, options, kdoc); WriteDebugString(printer, field, options, kdoc);
printer->Print(" */\n"); printer->Print(" */\n");
} }
@ -276,7 +281,7 @@ void WriteFieldAccessorDocComment(io::Printer* printer,
const Options options, const bool builder, const Options options, const bool builder,
const bool kdoc) { const bool kdoc) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, field, kdoc); WriteDocCommentBody(printer, field, options, kdoc);
WriteDebugString(printer, field, options, kdoc); WriteDebugString(printer, field, options, kdoc);
if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options); if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options);
switch (type) { switch (type) {
@ -336,7 +341,7 @@ void WriteFieldEnumValueAccessorDocComment(io::Printer* printer,
const bool builder, const bool builder,
const bool kdoc) { const bool kdoc) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, field, kdoc); WriteDocCommentBody(printer, field, options, kdoc);
WriteDebugString(printer, field, options, kdoc); WriteDebugString(printer, field, options, kdoc);
if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options); if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options);
switch (type) { switch (type) {
@ -407,7 +412,7 @@ void WriteFieldStringBytesAccessorDocComment(io::Printer* printer,
const bool builder, const bool builder,
const bool kdoc) { const bool kdoc) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, field, kdoc); WriteDocCommentBody(printer, field, options, kdoc);
WriteDebugString(printer, field, options, kdoc); WriteDebugString(printer, field, options, kdoc);
if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options); if (!kdoc) WriteDeprecatedJavadoc(printer, field, type, options);
switch (type) { switch (type) {
@ -461,9 +466,9 @@ void WriteFieldStringBytesAccessorDocComment(io::Printer* printer,
// Enum // Enum
void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_, void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_,
const bool kdoc) { const Options options, const bool kdoc) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, enum_, kdoc); WriteDocCommentBody(printer, enum_, options, kdoc);
if (kdoc) { if (kdoc) {
printer->Print( printer->Print(
" * Protobuf enum `$fullname$`\n" " * Protobuf enum `$fullname$`\n"
@ -478,9 +483,10 @@ void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_,
} }
void WriteEnumValueDocComment(io::Printer* printer, void WriteEnumValueDocComment(io::Printer* printer,
const EnumValueDescriptor* value) { const EnumValueDescriptor* value,
const Options options) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, value, /* kdoc */ false); WriteDocCommentBody(printer, value, options, /* kdoc */ false);
printer->Print( printer->Print(
" * <code>$def$</code>\n" " * <code>$def$</code>\n"
@ -489,19 +495,20 @@ void WriteEnumValueDocComment(io::Printer* printer,
} }
void WriteServiceDocComment(io::Printer* printer, void WriteServiceDocComment(io::Printer* printer,
const ServiceDescriptor* service) { const ServiceDescriptor* service,
const Options options) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, service, /* kdoc */ false); WriteDocCommentBody(printer, service, options, /* kdoc */ false);
printer->Print( printer->Print(
" * Protobuf service {@code $fullname$}\n" " * Protobuf service {@code $fullname$}\n"
" */\n", " */\n",
"fullname", EscapeJavadoc(service->full_name())); "fullname", EscapeJavadoc(service->full_name()));
} }
void WriteMethodDocComment(io::Printer* printer, void WriteMethodDocComment(io::Printer* printer, const MethodDescriptor* method,
const MethodDescriptor* method) { const Options options) {
printer->Print("/**\n"); printer->Print("/**\n");
WriteDocCommentBody(printer, method, /* kdoc */ false); WriteDocCommentBody(printer, method, options, /* kdoc */ false);
printer->Print( printer->Print(
" * <code>$def$</code>\n" " * <code>$def$</code>\n"
" */\n", " */\n",

38
src/google/protobuf/compiler/java/doc_comment.h
Unescape View File

@ -46,34 +46,28 @@ enum FieldAccessorType {
}; };
void WriteMessageDocComment(io::Printer* printer, const Descriptor* message, void WriteMessageDocComment(io::Printer* printer, const Descriptor* message,
const bool kdoc = false); Options options, bool kdoc = false);
void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field, void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field,
Options options, const bool kdoc = false); Options options, bool kdoc = false);
void WriteFieldAccessorDocComment(io::Printer* printer, void WriteFieldAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field, const FieldDescriptor* field,
const FieldAccessorType type, Options options, FieldAccessorType type, Options options,
const bool builder = false, bool builder = false, bool kdoc = false);
const bool kdoc = false); void WriteFieldEnumValueAccessorDocComment(
void WriteFieldEnumValueAccessorDocComment(io::Printer* printer, io::Printer* printer, const FieldDescriptor* field, FieldAccessorType type,
const FieldDescriptor* field, Options options, bool builder = false, bool kdoc = false);
const FieldAccessorType type, void WriteFieldStringBytesAccessorDocComment(
Options options, io::Printer* printer, const FieldDescriptor* field, FieldAccessorType type,
const bool builder = false, Options options, bool builder = false, bool kdoc = false);
const bool kdoc = false);
void WriteFieldStringBytesAccessorDocComment(io::Printer* printer,
const FieldDescriptor* field,
const FieldAccessorType type,
Options options,
const bool builder = false,
const bool kdoc = false);
void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_, void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_,
const bool kdoc = false); Options options, bool kdoc = false);
void WriteEnumValueDocComment(io::Printer* printer, void WriteEnumValueDocComment(io::Printer* printer,
const EnumValueDescriptor* value); const EnumValueDescriptor* value,
Options options);
void WriteServiceDocComment(io::Printer* printer, void WriteServiceDocComment(io::Printer* printer,
const ServiceDescriptor* service); const ServiceDescriptor* service, Options options);
void WriteMethodDocComment(io::Printer* printer, void WriteMethodDocComment(io::Printer* printer, const MethodDescriptor* method,
const MethodDescriptor* method); Options options);
// Exposed for testing only. // Exposed for testing only.
// Also called by proto1-Java code generator. // Also called by proto1-Java code generator.

10
src/google/protobuf/compiler/java/enum.cc
Unescape View File

@ -55,7 +55,7 @@ EnumGenerator::EnumGenerator(const EnumDescriptor* descriptor,
EnumGenerator::~EnumGenerator() {} EnumGenerator::~EnumGenerator() {}
void EnumGenerator::Generate(io::Printer* printer) { void EnumGenerator::Generate(io::Printer* printer) {
WriteEnumDocComment(printer, descriptor_); WriteEnumDocComment(printer, descriptor_, context_->options());
MaybePrintGeneratedAnnotation(context_, printer, descriptor_, immutable_api_); MaybePrintGeneratedAnnotation(context_, printer, descriptor_, immutable_api_);
if (!context_->options().opensource_runtime) { if (!context_->options().opensource_runtime) {
@ -84,7 +84,8 @@ void EnumGenerator::Generate(io::Printer* printer) {
vars["name"] = canonical_values_[i]->name(); vars["name"] = canonical_values_[i]->name();
vars["index"] = absl::StrCat(canonical_values_[i]->index()); vars["index"] = absl::StrCat(canonical_values_[i]->index());
vars["number"] = absl::StrCat(canonical_values_[i]->number()); vars["number"] = absl::StrCat(canonical_values_[i]->number());
WriteEnumValueDocComment(printer, canonical_values_[i]); WriteEnumValueDocComment(printer, canonical_values_[i],
context_->options());
if (canonical_values_[i]->options().deprecated()) { if (canonical_values_[i]->options().deprecated()) {
printer->Print("@java.lang.Deprecated\n"); printer->Print("@java.lang.Deprecated\n");
} }
@ -123,7 +124,7 @@ void EnumGenerator::Generate(io::Printer* printer) {
vars["classname"] = descriptor_->name(); vars["classname"] = descriptor_->name();
vars["name"] = aliases_[i].value->name(); vars["name"] = aliases_[i].value->name();
vars["canonical_name"] = aliases_[i].canonical_value->name(); vars["canonical_name"] = aliases_[i].canonical_value->name();
WriteEnumValueDocComment(printer, aliases_[i].value); WriteEnumValueDocComment(printer, aliases_[i].value, context_->options());
printer->Print( printer->Print(
vars, "public static final $classname$ $name$ = $canonical_name$;\n"); vars, "public static final $classname$ $name$ = $canonical_name$;\n");
printer->Annotate("name", aliases_[i].value); printer->Annotate("name", aliases_[i].value);
@ -138,7 +139,8 @@ void EnumGenerator::Generate(io::Printer* printer) {
vars["deprecation"] = descriptor_->value(i)->options().deprecated() vars["deprecation"] = descriptor_->value(i)->options().deprecated()
? "@java.lang.Deprecated " ? "@java.lang.Deprecated "
: ""; : "";
WriteEnumValueDocComment(printer, descriptor_->value(i)); WriteEnumValueDocComment(printer, descriptor_->value(i),
context_->options());
printer->Print(vars, printer->Print(vars,
"$deprecation$public static final int ${$$name$_VALUE$}$ = " "$deprecation$public static final int ${$$name$_VALUE$}$ = "
"$number$;\n"); "$number$;\n");

10
src/google/protobuf/compiler/java/enum_lite.cc
Unescape View File

@ -52,7 +52,7 @@ EnumLiteGenerator::EnumLiteGenerator(const EnumDescriptor* descriptor,
EnumLiteGenerator::~EnumLiteGenerator() {} EnumLiteGenerator::~EnumLiteGenerator() {}
void EnumLiteGenerator::Generate(io::Printer* printer) { void EnumLiteGenerator::Generate(io::Printer* printer) {
WriteEnumDocComment(printer, descriptor_); WriteEnumDocComment(printer, descriptor_, context_->options());
MaybePrintGeneratedAnnotation(context_, printer, descriptor_, immutable_api_); MaybePrintGeneratedAnnotation(context_, printer, descriptor_, immutable_api_);
printer->Print( printer->Print(
"$deprecation$public enum $classname$\n" "$deprecation$public enum $classname$\n"
@ -66,7 +66,8 @@ void EnumLiteGenerator::Generate(io::Printer* printer) {
absl::flat_hash_map<absl::string_view, std::string> vars; absl::flat_hash_map<absl::string_view, std::string> vars;
vars["name"] = canonical_values_[i]->name(); vars["name"] = canonical_values_[i]->name();
vars["number"] = absl::StrCat(canonical_values_[i]->number()); vars["number"] = absl::StrCat(canonical_values_[i]->number());
WriteEnumValueDocComment(printer, canonical_values_[i]); WriteEnumValueDocComment(printer, canonical_values_[i],
context_->options());
if (canonical_values_[i]->options().deprecated()) { if (canonical_values_[i]->options().deprecated()) {
printer->Print("@java.lang.Deprecated\n"); printer->Print("@java.lang.Deprecated\n");
} }
@ -90,7 +91,7 @@ void EnumLiteGenerator::Generate(io::Printer* printer) {
vars["classname"] = descriptor_->name(); vars["classname"] = descriptor_->name();
vars["name"] = aliases_[i].value->name(); vars["name"] = aliases_[i].value->name();
vars["canonical_name"] = aliases_[i].canonical_value->name(); vars["canonical_name"] = aliases_[i].canonical_value->name();
WriteEnumValueDocComment(printer, aliases_[i].value); WriteEnumValueDocComment(printer, aliases_[i].value, context_->options());
printer->Print( printer->Print(
vars, "public static final $classname$ $name$ = $canonical_name$;\n"); vars, "public static final $classname$ $name$ = $canonical_name$;\n");
printer->Annotate("name", aliases_[i].value); printer->Annotate("name", aliases_[i].value);
@ -105,7 +106,8 @@ void EnumLiteGenerator::Generate(io::Printer* printer) {
vars["deprecation"] = descriptor_->value(i)->options().deprecated() vars["deprecation"] = descriptor_->value(i)->options().deprecated()
? "@java.lang.Deprecated " ? "@java.lang.Deprecated "
: ""; : "";
WriteEnumValueDocComment(printer, descriptor_->value(i)); WriteEnumValueDocComment(printer, descriptor_->value(i),
context_->options());
printer->Print(vars, printer->Print(vars,
"$deprecation$public static final int ${$$name$_VALUE$}$ = " "$deprecation$public static final int ${$$name$_VALUE$}$ = "
"$number$;\n"); "$number$;\n");

5
src/google/protobuf/compiler/java/message.cc
Unescape View File

@ -295,7 +295,7 @@ void ImmutableMessageGenerator::Generate(io::Printer* printer) {
variables["deprecation"] = variables["deprecation"] =
descriptor_->options().deprecated() ? "@java.lang.Deprecated " : ""; descriptor_->options().deprecated() ? "@java.lang.Deprecated " : "";
WriteMessageDocComment(printer, descriptor_); WriteMessageDocComment(printer, descriptor_, context_->options());
MaybePrintGeneratedAnnotation(context_, printer, descriptor_, MaybePrintGeneratedAnnotation(context_, printer, descriptor_,
/* immutable = */ true); /* immutable = */ true);
if (!context_->options().opensource_runtime) { if (!context_->options().opensource_runtime) {
@ -1273,7 +1273,8 @@ void ImmutableMessageGenerator::GenerateKotlinMembers(
"message", "message",
EscapeKotlinKeywords(name_resolver_->GetClassName(descriptor_, true))); EscapeKotlinKeywords(name_resolver_->GetClassName(descriptor_, true)));
WriteMessageDocComment(printer, descriptor_, /* kdoc */ true); WriteMessageDocComment(printer, descriptor_, context_->options(),
/* kdoc */ true);
printer->Emit( printer->Emit(
{ {
io::Printer::Sub{"name_kt", absl::StrCat(descriptor_->name(), "Kt")} io::Printer::Sub{"name_kt", absl::StrCat(descriptor_->name(), "Kt")}

2
src/google/protobuf/compiler/java/message_builder.cc
Unescape View File

@ -88,7 +88,7 @@ MessageBuilderGenerator::MessageBuilderGenerator(const Descriptor* descriptor,
MessageBuilderGenerator::~MessageBuilderGenerator() {} MessageBuilderGenerator::~MessageBuilderGenerator() {}
void MessageBuilderGenerator::Generate(io::Printer* printer) { void MessageBuilderGenerator::Generate(io::Printer* printer) {
WriteMessageDocComment(printer, descriptor_); WriteMessageDocComment(printer, descriptor_, context_->options());
if (descriptor_->extension_range_count() > 0) { if (descriptor_->extension_range_count() > 0) {
printer->Print( printer->Print(
"public static final class Builder extends\n" "public static final class Builder extends\n"

2
src/google/protobuf/compiler/java/message_builder_lite.cc
Unescape View File

@ -59,7 +59,7 @@ MessageBuilderLiteGenerator::MessageBuilderLiteGenerator(
MessageBuilderLiteGenerator::~MessageBuilderLiteGenerator() {} MessageBuilderLiteGenerator::~MessageBuilderLiteGenerator() {}
void MessageBuilderLiteGenerator::Generate(io::Printer* printer) { void MessageBuilderLiteGenerator::Generate(io::Printer* printer) {
WriteMessageDocComment(printer, descriptor_); WriteMessageDocComment(printer, descriptor_, context_->options());
absl::flat_hash_map<absl::string_view, std::string> vars = { absl::flat_hash_map<absl::string_view, std::string> vars = {
{"{", ""}, {"{", ""},
{"}", ""}, {"}", ""},

5
src/google/protobuf/compiler/java/message_lite.cc
Unescape View File

@ -149,7 +149,7 @@ void ImmutableMessageLiteGenerator::Generate(io::Printer* printer) {
variables["deprecation"] = variables["deprecation"] =
descriptor_->options().deprecated() ? "@java.lang.Deprecated " : ""; descriptor_->options().deprecated() ? "@java.lang.Deprecated " : "";
WriteMessageDocComment(printer, descriptor_); WriteMessageDocComment(printer, descriptor_, context_->options());
MaybePrintGeneratedAnnotation(context_, printer, descriptor_, MaybePrintGeneratedAnnotation(context_, printer, descriptor_,
/* immutable = */ true); /* immutable = */ true);
@ -807,7 +807,8 @@ void ImmutableMessageLiteGenerator::GenerateKotlinMembers(
"message", "message",
EscapeKotlinKeywords(name_resolver_->GetClassName(descriptor_, true))); EscapeKotlinKeywords(name_resolver_->GetClassName(descriptor_, true)));
WriteMessageDocComment(printer, descriptor_, /* kdoc */ true); WriteMessageDocComment(printer, descriptor_, context_->options(),
/* kdoc */ true);
printer->Print("public object $name$Kt {\n", "name", descriptor_->name()); printer->Print("public object $name$Kt {\n", "name", descriptor_->name());
printer->Indent(); printer->Indent();
GenerateKotlinDsl(printer); GenerateKotlinDsl(printer);

4
src/google/protobuf/compiler/java/service.cc
Unescape View File

@ -43,7 +43,7 @@ ImmutableServiceGenerator::~ImmutableServiceGenerator() {}
void ImmutableServiceGenerator::Generate(io::Printer* printer) { void ImmutableServiceGenerator::Generate(io::Printer* printer) {
bool is_own_file = IsOwnFile(descriptor_, /* immutable = */ true); bool is_own_file = IsOwnFile(descriptor_, /* immutable = */ true);
WriteServiceDocComment(printer, descriptor_); WriteServiceDocComment(printer, descriptor_, context_->options());
MaybePrintGeneratedAnnotation(context_, printer, descriptor_, MaybePrintGeneratedAnnotation(context_, printer, descriptor_,
/* immutable = */ true); /* immutable = */ true);
if (!context_->options().opensource_runtime) { if (!context_->options().opensource_runtime) {
@ -162,7 +162,7 @@ void ImmutableServiceGenerator::GenerateNewReflectiveBlockingServiceMethod(
void ImmutableServiceGenerator::GenerateAbstractMethods(io::Printer* printer) { void ImmutableServiceGenerator::GenerateAbstractMethods(io::Printer* printer) {
for (int i = 0; i < descriptor_->method_count(); i++) { for (int i = 0; i < descriptor_->method_count(); i++) {
const MethodDescriptor* method = descriptor_->method(i); const MethodDescriptor* method = descriptor_->method(i);
WriteMethodDocComment(printer, method); WriteMethodDocComment(printer, method, context_->options());
GenerateMethodSignature(printer, method, IS_ABSTRACT); GenerateMethodSignature(printer, method, IS_ABSTRACT);
printer->Print(";\n\n"); printer->Print(";\n\n");
} }

Write Preview
Loading…
Cancel
Save