impl(docfx): return descriptions go through markdown (#11612)

coryan · web-flow · commit b84c39755807 · 2023-05-15T22:00:16.000-04:00
Finally found a way to convince docfx that we need the return type
descriptions to go through markdown.
diff --git a/docfx/doxygen2syntax.cc b/docfx/doxygen2syntax.cc
@@ -308,18 +308,22 @@ void AppendFunctionSyntax(YAML::Emitter& yaml, YamlContext const& ctx,
        << YAML::BeginMap                                           //
        << YAML::Key << "contents" << YAML::Value << YAML::Literal  //
        << FunctionSyntaxContent(node);
-  auto const rettype = HtmlEscape(LinkedTextType(node.child("type")));
+  auto const rettype = LinkedTextType(node.child("type"));
   if (!rettype.empty()) {
-    yaml << YAML::Key << "returns" << YAML::Value   //
-         << YAML::BeginSeq << YAML::BeginMap        //
-         << YAML::Key << "var_type" << YAML::Value  //
-         << YAML::DoubleQuoted << rettype;
+    // The `return` element accepts either a string for `type` or a sequence of
+    // strings. If `type` is a string then it must be UID pointing to another
+    // element in the documentation. That does not work in C++ where many
+    // functions return primitive types and Doxygen does not create links for
+    // the return type. So we create a sequence with a single element.
+    yaml << YAML::Key << "return" << YAML::Value << YAML::BeginMap  //
+         << YAML::Key << "type" << YAML::Value << YAML::BeginSeq    //
+         << YAML::DoubleQuoted << rettype << YAML::EndSeq;
     auto description = ReturnDescription(ctx, node);
     if (!description.empty()) {
       yaml << YAML::Key << "description" << YAML::Value << YAML::Literal
            << description;
     }
-    yaml << YAML::EndMap << YAML::EndSeq;
+    yaml << YAML::EndMap;
   }
   auto params = node.select_nodes("param");
   auto tparams = node.child("templateparamlist").children("param");
diff --git a/docfx/doxygen2syntax_test.cc b/docfx/doxygen2syntax_test.cc
@@ -672,10 +672,11 @@ TEST(Doxygen2Syntax, Function) {
     google::cloud::CompletionQueue::MakeRelativeTimer (
         std::chrono::duration< Rep, Period > duration
       )
-  returns:
-    - var_type: "future&lt; StatusOr&lt; std::chrono::system_clock::time_point &gt; &gt;"
-      description: |
-        a future that becomes satisfied after `duration` time has elapsed. The result of the future is the time at which it expired, or an error [Status](xref:classgoogle_1_1cloud_1_1Status) if the timer did not run to expiration (e.g. it was cancelled).
+  return:
+    type:
+      - "future< StatusOr< std::chrono::system_clock::time_point > >"
+    description: |
+      a future that becomes satisfied after `duration` time has elapsed. The result of the future is the time at which it expired, or an error [Status](xref:classgoogle_1_1cloud_1_1Status) if the timer did not run to expiration (e.g. it was cancelled).
   parameters:
     - id: duration
       var_type: "std::chrono::duration&lt; Rep, Period &gt;"
diff --git a/docfx/doxygen2yaml_test.cc b/docfx/doxygen2yaml_test.cc
@@ -734,10 +734,11 @@ TEST(Doxygen2Yaml, Function) {
         google::cloud::CompletionQueue::MakeRelativeTimer (
             std::chrono::duration< Rep, Period > duration
           )
-      returns:
-        - var_type: "future&lt; StatusOr&lt; std::chrono::system_clock::time_point &gt; &gt;"
-          description: |
-            a future that becomes satisfied after `duration` time has elapsed. The result of the future is the time at which it expired, or an error [Status](xref:classgoogle_1_1cloud_1_1Status) if the timer did not run to expiration (e.g. it was cancelled).
+      return:
+        type:
+          - "future< StatusOr< std::chrono::system_clock::time_point > >"
+        description: |
+          a future that becomes satisfied after `duration` time has elapsed. The result of the future is the time at which it expired, or an error [Status](xref:classgoogle_1_1cloud_1_1Status) if the timer did not run to expiration (e.g. it was cancelled).
       parameters:
         - id: duration
           var_type: "std::chrono::duration&lt; Rep, Period &gt;"
@@ -796,8 +797,9 @@ TEST(Doxygen2Yaml, MockedFunction) {
         google::cloud::kms_inventory_v1::KeyDashboardServiceConnection::ListCryptoKeys (
             google::cloud::kms::inventory::v1::ListCryptoKeysRequest request
           )
-      returns:
-        - var_type: "StreamRange&lt; google::cloud::kms::v1::CryptoKey &gt;"
+      return:
+        type:
+          - "StreamRange< google::cloud::kms::v1::CryptoKey >"
       parameters:
         - id: request
           var_type: "google::cloud::kms::inventory::v1::ListCryptoKeysRequest"
@@ -985,8 +987,9 @@ TEST(Doxygen2Yaml, Class) {
       contents: |
         Status const &
         google::cloud::RuntimeStatusError::status ()
-      returns:
-        - var_type: "Status const &"
+      return:
+        type:
+          - "Status const &"
       source:
         id: status
         path: google/cloud/status.h
