annotate generated classes

Summary: Add annotations to generated classes, enums and typedefs so that Glean can index the mapping from generated to source entities (see linked task for context). This will be used to extend codehub navigation from c++ to thrift to types. This is follows on what has been done for service functions D55445267. Reviewed By: iahs Differential Revision: D60142167 fbshipit-source-id: 5096c866f96531b5bd20288f902cf47c49f8e85e
facebook · Aug 3, 2024 · ca04e10 · ca04e10
1 parent f2390f7
commit ca04e10
Show file tree

Hide file tree

Showing 74 changed files with 632 additions and 0 deletions.
diff --git a/thrift/compiler/generate/templates/cpp2/common/class_docblock.mustache b/thrift/compiler/generate/templates/cpp2/common/class_docblock.mustache
@@ -0,0 +1,21 @@
+{{!
+
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+}}
+{{! The glean annotation is used by Glean indexers to map generated functions to thrift exceptions/structs/unions.
+    It can be moved within the docblock, as long as it stays on a single line }}
+/** Glean {"file": "{{program:autogen_path}}", "name": "{{struct:cpp_underlying_name}}", "kind": "{{#struct:exception?}}exception{{/struct:exception?}}{{^struct:exception?}}{{#struct:union?}}union{{/struct:union?}}{{^struct:union?}}struct{{/struct:union?}}{{/struct:exception?}}" } */
+{{! enforce new line }}
diff --git a/thrift/compiler/generate/templates/cpp2/common/enum_docblock.mustache b/thrift/compiler/generate/templates/cpp2/common/enum_docblock.mustache
@@ -0,0 +1,21 @@
+{{!
+
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+}}
+{{! The glean annotation is used by Glean indexers to map generated functions to thrift enums.
+    It can be moved within the docblock, as long as it stays on a single line }}
+/** Glean {"file": "{{program:autogen_path}}", "name": "{{enum:cpp_name}}", "kind": "enum" } */
+{{! enforce new line }}
diff --git a/thrift/compiler/generate/templates/cpp2/common/typedef_docblock.mustache b/thrift/compiler/generate/templates/cpp2/common/typedef_docblock.mustache
@@ -0,0 +1,21 @@
+{{!
+
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+}}
+{{! The glean annotation is used by Glean indexers to map generated functions to thrift typedefs.
+    It can be moved within the docblock, as long as it stays on a single line }}
+/** Glean {"file": "{{program:autogen_path}}", "name": "{{typedef:name}}", "kind": "typedef" } */
+{{! enforce new line }}
diff --git a/thrift/compiler/generate/templates/cpp2/module_types.h.mustache b/thrift/compiler/generate/templates/cpp2/module_types.h.mustache
@@ -101,13 +101,15 @@ using ::apache::thrift::detail::operator>=;
 
 {{#program:structs_and_typedefs}}
 {{^is_struct?}}
+{{ > common/typedef_docblock }}
 typedef {{typedef:cpp_type}} {{typedef:name}};
 {{/is_struct?}}
 {{#is_struct?}}
 
 {{#struct:extra_namespace}}
 namespace {{struct:extra_namespace}} {
 {{/struct:extra_namespace}}
+{{ > common/class_docblock }}
 class {{#struct:exception?}}FOLLY_EXPORT {{/struct:exception?}}{{struct:cpp_underlying_name}} {{!
 }}{{^struct:exception?}}{{^struct:virtual}}final {{/struct:virtual}}{{/struct:exception?}}{{!
 }}{{#struct:exception?}}: public virtual apache::thrift::TException{{/struct:exception?}} {

diff --git a/thrift/compiler/generate/templates/cpp2/module_types_h/declare_enums.mustache b/thrift/compiler/generate/templates/cpp2/module_types_h/declare_enums.mustache
@@ -20,6 +20,7 @@
 
 {{#program:enums}}
 
+{{ > common/enum_docblock }}
 enum {{^enum:cpp_is_unscoped}}class {{/enum:cpp_is_unscoped}}{{enum:cpp_name}}{{#enum:cpp_enum_type}} : {{enum:cpp_enum_type}}{{/enum:cpp_enum_type}} {
 {{#enum:values}}
   {{enum_value:cpp_name}} = {{enum_value:value}},

diff --git a/thrift/compiler/test/fixtures/adapter/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/adapter/out/cpp2/gen-cpp2/module_types.h
diff --git a/thrift/compiler/test/fixtures/adapter/out/cpp2_no_uri/gen-cpp2/module_no_uri_types.h b/thrift/compiler/test/fixtures/adapter/out/cpp2_no_uri/gen-cpp2/module_no_uri_types.h
@@ -48,6 +48,7 @@ using ::apache::thrift::detail::operator<=;
 using ::apache::thrift::detail::operator>=;
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/adapter/src/module_no_uri.thrift", "name": "RefUnion", "kind": "union" } */
 class RefUnion final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/any/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/any/out/cpp2/gen-cpp2/module_types.h
@@ -62,6 +62,7 @@ using ::apache::thrift::detail::operator>=;
 
 
 namespace detail {
+/** Glean {"file": "thrift/compiler/test/fixtures/any/src/module.thrift", "name": "MyStruct", "kind": "struct" } */
 class MyStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -223,6 +224,7 @@ unsigned long MyStruct::read(Protocol_* iprot) {
 using MyStruct = ::apache::thrift::adapt_detail::adapted_t<::my::Adapter1, ::facebook::thrift::compiler::test::fixtures::any::detail::MyStruct>;
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/any/src/module.thrift", "name": "MyUnion", "kind": "union" } */
 class MyUnion final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -437,6 +439,7 @@ unsigned long MyUnion::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/any/src/module.thrift", "name": "MyException", "kind": "exception" } */
 class FOLLY_EXPORT MyException : public virtual apache::thrift::TException {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/basic-annotations/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/basic-annotations/out/cpp2/gen-cpp2/module_types.h
@@ -82,6 +82,7 @@ APACHE_THRIFT_DEFINE_ACCESSOR(password);
 // BEGIN declare_enums
 namespace cpp2 {
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "YourEnum", "kind": "enum" } */
 enum class YourEnum {
   MyValue1 = 0,
   MyValue2 = 1,
@@ -157,6 +158,7 @@ using ::apache::thrift::detail::operator>=;
 
 
 namespace detail {
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "YourUnion", "kind": "union" } */
 class YourUnion final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -291,9 +293,11 @@ unsigned long YourUnion::read(Protocol_* iprot) {
 
 using YourUnion = ::apache::thrift::adapt_detail::adapted_t<::StaticCast, ::cpp2::detail::YourUnion>;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "list_string_6884", "kind": "typedef" } */
 typedef std::deque<std::string> list_string_6884;
 
 namespace detail {
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "YourStruct", "kind": "struct" } */
 class YourStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -894,9 +898,12 @@ unsigned long YourStruct::read(Protocol_* iprot) {
 
 using YourStruct = ::apache::thrift::adapt_detail::adapted_t<::StaticCast, ::cpp2::detail::YourStruct>;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "AwesomeStruct", "kind": "typedef" } */
 typedef ::cpp2::YourStruct AwesomeStruct;
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "FantasticStruct", "kind": "typedef" } */
 typedef ::cpp2::YourStruct FantasticStruct;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "MyStructNestedAnnotation", "kind": "struct" } */
 class MyStructNestedAnnotation final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1055,6 +1062,7 @@ unsigned long MyStructNestedAnnotation::read(Protocol_* iprot) {
 
 
 namespace detail {
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "YourException", "kind": "exception" } */
 class FOLLY_EXPORT YourException : public virtual apache::thrift::TException {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1164,6 +1172,7 @@ unsigned long YourException::read(Protocol_* iprot) {
 using YourException = ::apache::thrift::adapt_detail::adapted_t<::StaticCast, ::cpp2::detail::YourException>;
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-annotations/src/module.thrift", "name": "SecretStruct", "kind": "struct" } */
 class SecretStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/basic-enum/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/basic-enum/out/cpp2/gen-cpp2/module_types.h
@@ -32,18 +32,21 @@ APACHE_THRIFT_DEFINE_ACCESSOR(myBigEnum);
 // BEGIN declare_enums
 namespace test::fixtures::enumstrict {
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-enum/src/module.thrift", "name": "EmptyEnum", "kind": "enum" } */
 enum class EmptyEnum {
 };
 
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-enum/src/module.thrift", "name": "MyEnum", "kind": "enum" } */
 enum class MyEnum {
   ONE = 1,
   TWO = 2,
 };
 
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-enum/src/module.thrift", "name": "MyBigEnum", "kind": "enum" } */
 enum class MyBigEnum {
   UNKNOWN = 0,
   ONE = 1,
@@ -171,6 +174,7 @@ using ::apache::thrift::detail::operator<=;
 using ::apache::thrift::detail::operator>=;
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-enum/src/module.thrift", "name": "MyStruct", "kind": "struct" } */
 class MyStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/basic-stack-arguments/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/basic-stack-arguments/out/cpp2/gen-cpp2/module_types.h
@@ -32,6 +32,7 @@ APACHE_THRIFT_DEFINE_ACCESSOR(MyStringField);
 // BEGIN declare_enums
 namespace cpp2 {
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-stack-arguments/src/module.thrift", "name": "MyEnum", "kind": "enum" } */
 enum class MyEnum {
   MyValue1 = 0,
   MyValue2 = 1,
@@ -95,6 +96,7 @@ using ::apache::thrift::detail::operator<=;
 using ::apache::thrift::detail::operator>=;
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-stack-arguments/src/module.thrift", "name": "MyStruct", "kind": "struct" } */
 class MyStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/basic-structured-annotations/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/basic-structured-annotations/out/cpp2/gen-cpp2/module_types.h
@@ -104,6 +104,7 @@ APACHE_THRIFT_DEFINE_ACCESSOR(second);
 // BEGIN declare_enums
 namespace test::fixtures::basic-structured-annotations {
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "MyEnum", "kind": "enum" } */
 enum class MyEnum {
   UNKNOWN = 0,
   ONE = 1,
@@ -178,10 +179,14 @@ using ::apache::thrift::detail::operator>;
 using ::apache::thrift::detail::operator<=;
 using ::apache::thrift::detail::operator>=;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "annotated_with_default_string", "kind": "typedef" } */
 typedef ::std::string annotated_with_default_string;
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "annotated_inline_string", "kind": "typedef" } */
 typedef ::std::string annotated_inline_string;
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "annotated_inline_i64", "kind": "typedef" } */
 typedef ::std::int64_t annotated_inline_i64;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "runtime_annotation", "kind": "struct" } */
 class runtime_annotation final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -277,6 +282,7 @@ unsigned long runtime_annotation::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "structured_annotation_inline", "kind": "struct" } */
 class structured_annotation_inline final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -489,6 +495,7 @@ unsigned long structured_annotation_inline::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "structured_annotation_with_default", "kind": "struct" } */
 class structured_annotation_with_default final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -647,6 +654,7 @@ unsigned long structured_annotation_with_default::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "structured_annotation_forward", "kind": "struct" } */
 class structured_annotation_forward final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -799,6 +807,7 @@ unsigned long structured_annotation_forward::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "structured_annotation_recursive", "kind": "struct" } */
 class structured_annotation_recursive final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1052,6 +1061,7 @@ unsigned long structured_annotation_recursive::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "structured_annotation_nested", "kind": "struct" } */
 class structured_annotation_nested final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1263,6 +1273,7 @@ unsigned long structured_annotation_nested::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "MyStruct", "kind": "struct" } */
 class MyStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1588,6 +1599,7 @@ unsigned long MyStruct::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "MyException", "kind": "exception" } */
 class FOLLY_EXPORT MyException : public virtual apache::thrift::TException {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1756,6 +1768,7 @@ unsigned long MyException::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic-structured-annotations/src/module.thrift", "name": "MyUnion", "kind": "union" } */
 class MyUnion final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;

diff --git a/thrift/compiler/test/fixtures/basic/out/cpp2/gen-cpp2/module_types.h b/thrift/compiler/test/fixtures/basic/out/cpp2/gen-cpp2/module_types.h
@@ -152,13 +152,15 @@ APACHE_THRIFT_DEFINE_ACCESSOR(reserved_field);
 // BEGIN declare_enums
 namespace test::fixtures::basic {
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyEnum", "kind": "enum" } */
 enum class MyEnum {
   MyValue1 = 0,
   MyValue2 = 1,
 };
 
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "HackEnum", "kind": "enum" } */
 enum class HackEnum {
   Value1 = 0,
   Value2 = 1,
@@ -252,9 +254,12 @@ using ::apache::thrift::detail::operator>;
 using ::apache::thrift::detail::operator<=;
 using ::apache::thrift::detail::operator>=;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyEnumAlias", "kind": "typedef" } */
 typedef ::test::fixtures::basic::MyEnum MyEnumAlias;
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyDataItemAlias", "kind": "typedef" } */
 typedef ::test::fixtures::basic::MyDataItem MyDataItemAlias;
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyDataItem", "kind": "struct" } */
 class MyDataItem final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -350,6 +355,7 @@ unsigned long MyDataItem::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyStruct", "kind": "struct" } */
 class MyStruct final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -943,6 +949,7 @@ unsigned long MyStruct::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "Containers", "kind": "struct" } */
 class Containers final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1201,6 +1208,7 @@ unsigned long Containers::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyUnion", "kind": "union" } */
 class MyUnion final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1629,6 +1637,7 @@ unsigned long MyUnion::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyException", "kind": "exception" } */
 class FOLLY_EXPORT MyException : public virtual apache::thrift::TException {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -1957,6 +1966,7 @@ unsigned long MyException::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "MyExceptionWithMessage", "kind": "exception" } */
 class FOLLY_EXPORT MyExceptionWithMessage : public virtual apache::thrift::TException {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -2286,6 +2296,7 @@ unsigned long MyExceptionWithMessage::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "ReservedKeyword", "kind": "struct" } */
 class ReservedKeyword final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;
@@ -2438,6 +2449,7 @@ unsigned long ReservedKeyword::read(Protocol_* iprot) {
 }
 
 
+/** Glean {"file": "thrift/compiler/test/fixtures/basic/src/module.thrift", "name": "UnionToBeRenamed", "kind": "union" } */
 class UnionToBeRenamed final  {
  private:
   friend struct ::apache::thrift::detail::st::struct_private_access;