doc: document Start and Await methods and mocks

CHANGELOG.md

@@ -6,6 +6,17 @@ breaking changes in the upcoming 3.x release. This release is scheduled for
 
 ## v2.26.0 - TBD
 
+### BREAKING TESTING CHANGES
+If you don't have tests that `EXPECT_CALL` on methods in `MockConnection` that
+perform Long Running Operations (LRO), these changes will not affect you.
+
+With the addition of new methods to support starting Long Running Operations
+(LRO) synchronously and awaiting their completion separately, the overload set
+for the preexisting LRO methods have been expanded. Uses of `EXPECT_CALL` that
+do not have matchers for the arguments will be ambiguous. To quickly remedy this
+change instances of `EXPECT_CALL(*mock, Method)` to
+`EXPECT_CALL(*mock, Method(_))`.
+
 ### New Libraries
 
 We are happy to announce the following GA libraries. Unless specifically noted,

generator/internal/client_generator.cc

@@ -176,6 +176,7 @@ R"""(  std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
                 // clang-format on
                 {method_string},
                 {"\n"},
+                {FormatStartMethodComments()},
                 {IsResponseTypeEmpty,
                  // clang-format off
                     "  Status\n",
@@ -267,6 +268,7 @@ R"""(  std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
     "  future<StatusOr<$longrunning_deduced_response_type$>>\n"},
    {"  $method_name$($request_type$ const& request, Options opts = {});\n"},
    {"\n"},
+                {FormatStartMethodComments()},
                  // clang-format on
                  {IsResponseTypeEmpty,
                   // clang-format off
@@ -276,6 +278,7 @@ R"""(  std::unique_ptr<::google::cloud::AsyncStreamingReadWriteRpc<
     "NoAwaitTag, "
     "$request_type$ const& request, Options opts = {});\n\n"},
                  // clang-format on
+                 {FormatAwaitMethodComments()},
                  {IsResponseTypeEmpty,
                   // clang-format off
     "  future<Status>\n",

generator/internal/format_method_comments.cc

@@ -258,6 +258,34 @@ bool CheckMethodCommentSubstitutions() {
   return all_substitutions_used;
 }
 
+std::string FormatStartMethodComments() {
+  return R"""(  // clang-format off
+  ///
+  /// @copydoc $method_name$
+  ///
+  /// Specifying the [`NoAwaitTag`] immediately returns the
+  /// [`$longrunning_operation_type$`] that corresponds to the Long Running
+  /// Operation that has been started. No polling for operation status occurs.
+  ///
+  /// [`NoAwaitTag`]: @ref google::cloud::NoAwaitTag
+  ///
+  // clang-format on
+)""";
+}
+
+std::string FormatAwaitMethodComments() {
+  return R"""(  // clang-format off
+  ///
+  /// @copydoc $method_name$
+  ///
+  /// This method accepts a `$longrunning_operation_type$` that corresponds
+  /// to a previously started Long Running Operation (LRO) and polls the status
+  /// of the LRO in the background.
+  ///
+  // clang-format on
+)""";
+}
+
 }  // namespace generator_internal
 }  // namespace cloud
 }  // namespace google

generator/internal/format_method_comments.h

@@ -37,6 +37,16 @@ std::string FormatMethodComments(
  */
 bool CheckMethodCommentSubstitutions();
 
+/**
+ *  Comments for LRO Start overload.
+ */
+std::string FormatStartMethodComments();
+
+/**
+ * Comments for LRO Await overload.
+ */
+std::string FormatAwaitMethodComments();
+
 }  // namespace generator_internal
 }  // namespace cloud
 }  // namespace google

generator/internal/mock_connection_generator.cc

@@ -103,10 +103,15 @@ class $mock_connection_class_name$ : public $product_namespace$::$connection_cla
                  Not(IsPaginated))),
          MethodPattern(
              {
+                 {// clang-format off
+    "\n  // Due to additional overloads for this method\n"
+    "  // EXPECT_CALL(*mock, $method_name$) is now ambiguous. Use\n"
+    "  // EXPECT_CALL(*mock, $method_name$(_)) instead.\n"},
+                 // clang-format on
                  {IsResponseTypeEmpty,
                   // clang-format off
-    "\n  MOCK_METHOD(future<Status>,\n",
-    "\n  MOCK_METHOD(future<StatusOr<$longrunning_deduced_response_type$>>,\n"},
+    "  MOCK_METHOD(future<Status>,\n",
+    "  MOCK_METHOD(future<StatusOr<$longrunning_deduced_response_type$>>,\n"},
    {"  $method_name$,\n"
     "  ($request_type$ const& request), (override));\n\n",},
                  // clang-format on