From 36650a07cf98ee4e734e07f2403fe5d20e300fc8 Mon Sep 17 00:00:00 2001 From: Thomas Van Lenten Date: Mon, 7 Mar 2016 12:07:03 -0500 Subject: HeaderDoc support in the library and generated sources - Convert most of the core library headers over to HeaderDoc format. - Switch the generated comments over to HeaderDoc. - Create GPBCodedOutputStream_PackagePrivate and move some things into there that should be more internal. --- .../protobuf/compiler/objectivec/objectivec_enum.cc | 6 +++++- .../compiler/objectivec/objectivec_enum_field.cc | 5 +++++ .../protobuf/compiler/objectivec/objectivec_field.cc | 16 +++++++++------- .../protobuf/compiler/objectivec/objectivec_file.cc | 14 ++++++++------ .../protobuf/compiler/objectivec/objectivec_helpers.cc | 10 ++++------ .../protobuf/compiler/objectivec/objectivec_helpers.h | 1 + .../protobuf/compiler/objectivec/objectivec_oneof.cc | 1 + 7 files changed, 33 insertions(+), 20 deletions(-) (limited to 'src') diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc index d6f01c60..857d24a4 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum.cc @@ -80,10 +80,12 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { if (HasPreservingUnknownEnumSemantics(descriptor_->file())) { // Include the unknown value. printer->Print( + "/// Value used if any message's field encounters a value that is not defined\n" + "/// by this enum. The message will also have C functions to get/set the rawValue\n" + "/// of the field.\n" "$name$_GPBUnrecognizedEnumeratorValue = kGPBUnrecognizedEnumeratorValue,\n", "name", name_); } - for (int i = 0; i < all_values_.size(); i++) { SourceLocation location; if (all_values_[i]->GetSourceLocation(&location)) { @@ -107,6 +109,8 @@ void EnumGenerator::GenerateHeader(io::Printer* printer) { "\n" "GPBEnumDescriptor *$name$_EnumDescriptor(void);\n" "\n" + "/// Checks to see if the given value is defined by the enum or was not known at\n" + "/// the time this source was generated.\n" "BOOL $name$_IsValidValue(int32_t value);\n" "\n", "name", name_); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc index ecc77f6b..cfbb8c52 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_enum_field.cc @@ -87,7 +87,12 @@ void EnumFieldGenerator::GenerateCFunctionDeclarations( printer->Print( variables_, + "/// Fetches the raw value of a @c $owning_message_class$'s @c $name$ property, even\n" + "/// if the value was not defined by the enum at the time the code was generated.\n" "int32_t $owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message);\n" + "/// Sets the raw value of an @c $owning_message_class$'s @c $name$ property, allowing\n" + "/// it to be set to a value that was not defined by the enum at the time the code\n" + "/// was generated.\n" "void Set$owning_message_class$_$capitalized_name$_RawValue($owning_message_class$ *message, int32_t value);\n" "\n"); } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_field.cc b/src/google/protobuf/compiler/objectivec/objectivec_field.cc index 09341820..8697e225 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_field.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_field.cc @@ -270,15 +270,15 @@ void SingleFieldGenerator::GenerateFieldStorageDeclaration( void SingleFieldGenerator::GeneratePropertyDeclaration( io::Printer* printer) const { printer->Print(variables_, "$comments$"); + printer->Print( + variables_, + "@property(nonatomic, readwrite) $property_type$ $name$;\n" + "\n"); if (WantsHasProperty()) { printer->Print( variables_, "@property(nonatomic, readwrite) BOOL has$capitalized_name$;\n"); } - printer->Print( - variables_, - "@property(nonatomic, readwrite) $property_type$ $name$;\n" - "\n"); } void SingleFieldGenerator::GeneratePropertyImplementation( @@ -326,14 +326,15 @@ void ObjCObjFieldGenerator::GeneratePropertyDeclaration( // conventions (init*, new*, etc.) printer->Print(variables_, "$comments$"); + printer->Print( + variables_, + "@property(nonatomic, readwrite, $property_storage_attribute$, null_resettable) $property_type$ *$name$$storage_attribute$;\n"); if (WantsHasProperty()) { printer->Print( variables_, + "/// Test to see if @c $name$ has been set.\n" "@property(nonatomic, readwrite) BOOL has$capitalized_name$;\n"); } - printer->Print( - variables_, - "@property(nonatomic, readwrite, $property_storage_attribute$, null_resettable) $property_type$ *$name$$storage_attribute$;\n"); if (IsInitName(variables_.find("name")->second)) { // If property name starts with init we need to annotate it to get past ARC. // http://stackoverflow.com/questions/18723226/how-do-i-annotate-an-objective-c-property-with-an-objc-method-family/18723227#18723227 @@ -385,6 +386,7 @@ void RepeatedFieldGenerator::GeneratePropertyDeclaration( "$comments$" "$array_comment$" "@property(nonatomic, readwrite, strong, null_resettable) $array_property_type$ *$name$$storage_attribute$;\n" + "/// The number of items in @c $name$ without causing the array to be created.\n" "@property(nonatomic, readonly) NSUInteger $name$_Count;\n"); if (IsInitName(variables_.find("name")->second)) { // If property name starts with init we need to annotate it to get past ARC. diff --git a/src/google/protobuf/compiler/objectivec/objectivec_file.cc b/src/google/protobuf/compiler/objectivec/objectivec_file.cc index cdf9ebbc..16199884 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_file.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_file.cc @@ -151,13 +151,15 @@ void FileGenerator::GenerateHeader(io::Printer *printer) { printer->Print( "#pragma mark - $root_class_name$\n" "\n" + "/// Exposes the extension registry for this file.\n" + "///\n" + "/// The base class provides:\n" + "/// @code\n" + "/// + (GPBExtensionRegistry *)extensionRegistry;\n" + "/// @endcode\n" + "/// which is a @c GPBExtensionRegistry that includes all the extensions defined by\n" + "/// this file and all files that it depends on.\n" "@interface $root_class_name$ : GPBRootObject\n" - "\n" - "// The base class provides:\n" - "// + (GPBExtensionRegistry *)extensionRegistry;\n" - "// which is an GPBExtensionRegistry that includes all the extensions defined by\n" - "// this file and all files that it depends on.\n" - "\n" "@end\n" "\n", "root_class_name", root_class_name_); diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc index 77a378c8..24ff2b56 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.cc @@ -771,16 +771,14 @@ string BuildCommentsString(const SourceLocation& location) { while (!lines.empty() && lines.back().empty()) { lines.pop_back(); } - string prefix("//"); + string prefix("///"); string suffix("\n"); string final_comments; for (int i = 0; i < lines.size(); i++) { - // We use $ for delimiters, so replace comments with dollars with - // html escaped version. - // None of the other compilers handle this (as of this writing) but we - // ran into it once, so just to be safe. + // HeaderDoc uses '\' and '@' for markers; escape them. + const string line = StringReplace(lines[i], "\\", "\\\\", true); final_comments += - prefix + StringReplace(lines[i], "$", "$", true) + suffix; + prefix + StringReplace(line, "@", "\\@", true) + suffix; } return final_comments; } diff --git a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h index 5b2dd190..a301493e 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_helpers.h +++ b/src/google/protobuf/compiler/objectivec/objectivec_helpers.h @@ -146,6 +146,7 @@ string DefaultValue(const FieldDescriptor* field); string BuildFlagsString(const vector& strings); +// Builds a HeaderDoc style comment out of the comments in the .proto file. string BuildCommentsString(const SourceLocation& location); // Checks the prefix for a given file and outputs any warnings needed, if diff --git a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc index 3cb87482..24e6df07 100644 --- a/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc +++ b/src/google/protobuf/compiler/objectivec/objectivec_oneof.cc @@ -104,6 +104,7 @@ void OneofGenerator::GeneratePublicCasePropertyDeclaration( void OneofGenerator::GenerateClearFunctionDeclaration(io::Printer* printer) { printer->Print( variables_, + "/// Clears whatever value was set for the oneof '$name$'.\n" "void $owning_message_class$_Clear$capitalized_name$OneOfCase($owning_message_class$ *message);\n"); } -- cgit v1.2.3