[Storage] Fix formatting, missing doxygen docs, and add release notes

Co-authored-by: AustinBenoit <22805659+AustinBenoit@users.noreply.github.com>

Author: google-labs-jules[bot]

release_build_files/readme.md

@@ -615,6 +615,7 @@ code.
 ## Release Notes
 ### 13.5.0
 -   Changes
+    - Storage: Added `List` API across all platforms.
     - General (Android): Update to Firebase Android BoM version 34.10.0.
     - General (iOS): Update to Firebase Cocoapods version 12.10.0.
     - App Check: Add in support for Limited Use Tokens.

storage/integration_test/src/integration_test.cc

@@ -1651,18 +1651,16 @@ TEST_F(FirebaseStorageTest, TestList) {
 
   // Create some files and folders
   std::vector<std::string> file_paths = {
-      "folderA/file1.txt",
-      "folderA/file2.txt",
-      "folderB/file3.txt",
-      "folderC/file4.txt",
-      "rootFile.txt"
-  };
+      "folderA/file1.txt", "folderA/file2.txt", "folderB/file3.txt",
+      "folderC/file4.txt", "rootFile.txt"};
 
   for (const std::string& path : file_paths) {
     firebase::storage::StorageReference ref = root.Child(path);
     WaitForCompletion(RunWithRetry([&]() {
-      return ref.PutBytes(&kSimpleTestFile[0], kSimpleTestFile.size());
-    }), "PutBytes List Test");
+                        return ref.PutBytes(&kSimpleTestFile[0],
+                                            kSimpleTestFile.size());
+                      }),
+                      "PutBytes List Test");
   }
 
   // Allow some time for index to catch up
@@ -1671,9 +1669,10 @@ TEST_F(FirebaseStorageTest, TestList) {
   // List all at the root of the test folder
   firebase::Future<firebase::storage::StorageListResult> list_future;
   WaitForCompletion(RunWithRetry([&]() {
-    list_future = root.List(1000);
-    return list_future;
-  }), "ListRoot");
+                      list_future = root.List(1000);
+                      return list_future;
+                    }),
+                    "ListRoot");
 
   EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
 
@@ -1702,9 +1701,10 @@ TEST_F(FirebaseStorageTest, TestList) {
   // Test pagination
   firebase::storage::StorageReference folderA = root.Child("folderA");
   WaitForCompletion(RunWithRetry([&]() {
-    list_future = folderA.List(1);
-    return list_future;
-  }), "ListFolderA_Page1");
+                      list_future = folderA.List(1);
+                      return list_future;
+                    }),
+                    "ListFolderA_Page1");
 
   EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
   list_result = list_future.result();
@@ -1714,9 +1714,10 @@ TEST_F(FirebaseStorageTest, TestList) {
   std::string next_token = list_result->next_page_token();
 
   WaitForCompletion(RunWithRetry([&]() {
-    list_future = folderA.List(1, next_token.c_str());
-    return list_future;
-  }), "ListFolderA_Page2");
+                      list_future = folderA.List(1, next_token.c_str());
+                      return list_future;
+                    }),
+                    "ListFolderA_Page2");
 
   EXPECT_EQ(list_future.error(), firebase::storage::kErrorNone);
   list_result = list_future.result();

storage/src/android/storage_reference_android.cc

@@ -284,27 +284,27 @@ void StorageReferenceInternal::FutureCallback(JNIEnv* env, jobject result,
 
     std::vector<StorageReference> prefixes;
     if (prefixes_list) {
-      jint size = env->CallIntMethod(
-          prefixes_list, list::GetMethodId(list::kSize));
+      jint size =
+          env->CallIntMethod(prefixes_list, list::GetMethodId(list::kSize));
       for (jint i = 0; i < size; ++i) {
         jobject prefix_obj = env->CallObjectMethod(
             prefixes_list, list::GetMethodId(list::kGet), i);
-        prefixes.push_back(
-            StorageReference(new StorageReferenceInternal(data->storage, prefix_obj)));
+        prefixes.push_back(StorageReference(
+            new StorageReferenceInternal(data->storage, prefix_obj)));
         env->DeleteLocalRef(prefix_obj);
       }
       env->DeleteLocalRef(prefixes_list);
     }
 
     std::vector<StorageReference> items;
     if (items_list) {
-      jint size = env->CallIntMethod(
-          items_list, list::GetMethodId(list::kSize));
+      jint size =
+          env->CallIntMethod(items_list, list::GetMethodId(list::kSize));
       for (jint i = 0; i < size; ++i) {
-        jobject item_obj = env->CallObjectMethod(
-            items_list, list::GetMethodId(list::kGet), i);
-        items.push_back(
-            StorageReference(new StorageReferenceInternal(data->storage, item_obj)));
+        jobject item_obj =
+            env->CallObjectMethod(items_list, list::GetMethodId(list::kGet), i);
+        items.push_back(StorageReference(
+            new StorageReferenceInternal(data->storage, item_obj)));
         env->DeleteLocalRef(item_obj);
       }
       env->DeleteLocalRef(items_list);
@@ -318,7 +318,8 @@ void StorageReferenceInternal::FutureCallback(JNIEnv* env, jobject result,
 
     StorageListResultInternal* list_internal =
         new StorageListResultInternal(prefixes, items, page_token);
-    data->impl->CompleteWithResult(handle, kErrorNone, StorageListResult(list_internal));
+    data->impl->CompleteWithResult(handle, kErrorNone,
+                                   StorageListResult(list_internal));
   } else if (result && env->IsInstanceOf(result, util::string::GetClass())) {
     LogDebug("FutureCallback: Completing a Future from a String.");
     // Complete a Future<std::string> from a Java String object.
@@ -754,20 +755,21 @@ Future<Metadata> StorageReferenceInternal::PutFileLastResult() {
       future()->LastResult(kStorageReferenceFnPutFile));
 }
 
-Future<StorageListResult> StorageReferenceInternal::List(int max_results_per_page,
-                                                         const char *page_token) {
+Future<StorageListResult> StorageReferenceInternal::List(
+    int max_results_per_page, const char* page_token) {
   JNIEnv* env = storage_->app()->GetJNIEnv();
   ReferenceCountedFutureImpl* future_impl = future();
   FutureHandle handle =
       future_impl->Alloc<StorageListResult>(kStorageReferenceFnList);
 
-  jstring java_page_token = page_token ? env->NewStringUTF(page_token) : nullptr;
+  jstring java_page_token =
+      page_token ? env->NewStringUTF(page_token) : nullptr;
   jobject task = env->CallObjectMethod(
       obj_, storage_reference::GetMethodId(storage_reference::kList),
       max_results_per_page, java_page_token);
 
   if (java_page_token) {
-      env->DeleteLocalRef(java_page_token);
+    env->DeleteLocalRef(java_page_token);
   }
 
   util::RegisterCallbackOnTask(

storage/src/android/storage_reference_android.h

@@ -131,7 +131,7 @@ class StorageReferenceInternal {
 
   // List items (files) and prefixes (folders) under this StorageReference.
   Future<StorageListResult> List(int max_results_per_page,
-                                 const char *page_token);
+                                 const char* page_token);
 
   // Returns the result of the most recent call to List();
   Future<StorageListResult> ListLastResult();

storage/src/common/list_result.cc

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 #include "storage/src/include/firebase/storage/list_result.h"
+
 #include "storage/src/common/list_result_internal.h"
 
 namespace firebase {
@@ -26,14 +27,19 @@ StorageListResult::~StorageListResult() {
 }
 
 StorageListResult::StorageListResult(const StorageListResult& other)
-    : internal_(other.internal_ ? new internal::StorageListResultInternal(*other.internal_) : nullptr) {}
+    : internal_(other.internal_
+                    ? new internal::StorageListResultInternal(*other.internal_)
+                    : nullptr) {}
 
-StorageListResult& StorageListResult::operator=(const StorageListResult& other) {
+StorageListResult& StorageListResult::operator=(
+    const StorageListResult& other) {
   if (this == &other) {
     return *this;
   }
   delete internal_;
-  internal_ = other.internal_ ? new internal::StorageListResultInternal(*other.internal_) : nullptr;
+  internal_ = other.internal_
+                  ? new internal::StorageListResultInternal(*other.internal_)
+                  : nullptr;
   return *this;
 }
 
@@ -68,7 +74,8 @@ const char* StorageListResult::next_page_token() const {
   return internal_ ? internal_->next_page_token() : nullptr;
 }
 
-StorageListResult::StorageListResult(internal::StorageListResultInternal* internal)
+StorageListResult::StorageListResult(
+    internal::StorageListResultInternal* internal)
     : internal_(internal) {}
 
 }  // namespace storage

storage/src/common/storage_reference.cc

@@ -247,7 +247,7 @@ Future<Metadata> StorageReference::PutFileLastResult() {
 }
 
 Future<StorageListResult> StorageReference::List(int max_results_per_page,
-                                                 const char *page_token) {
+                                                 const char* page_token) {
   return internal_ ? internal_->List(max_results_per_page, page_token)
                    : Future<StorageListResult>();
 }

storage/src/desktop/curl_requests.cc

@@ -19,11 +19,11 @@
 #include <string>
 
 #include "app/rest/util.h"
+#include "storage/src/common/list_result_internal.h"
 #include "storage/src/desktop/metadata_desktop.h"
 #include "storage/src/desktop/rest_operation.h"
 #include "storage/src/include/firebase/storage/common.h"
 #include "storage/src/include/firebase/storage/metadata.h"
-#include "storage/src/common/list_result_internal.h"
 
 namespace firebase {
 namespace storage {
@@ -285,7 +285,8 @@ void ReturnedListResponse::MarkCompleted() {
             if (!path.empty() && path.back() == '/') {
               path.pop_back();
             }
-            prefixes.push_back(storage_reference_.storage()->GetReference(path.c_str()));
+            prefixes.push_back(
+                storage_reference_.storage()->GetReference(path.c_str()));
           }
         }
       }

storage/src/desktop/storage_reference_desktop.cc

@@ -694,60 +694,62 @@ StorageReferenceInternal* StorageReferenceInternal::GetParent() {
   return new StorageReferenceInternal(storageUri_.GetParent(), storage_);
 }
 
-Future<StorageListResult> StorageReferenceInternal::List(int max_results_per_page,
-                                                         const char *page_token) {
+Future<StorageListResult> StorageReferenceInternal::List(
+    int max_results_per_page, const char* page_token) {
   auto* future_api = future();
-  auto handle = future_api->SafeAlloc<StorageListResult>(kStorageReferenceFnList);
+  auto handle =
+      future_api->SafeAlloc<StorageListResult>(kStorageReferenceFnList);
 
   std::string token_str = page_token ? page_token : "";
-  auto send_request_funct{[&, max_results_per_page, token_str]() -> BlockingResponse* {
-    auto* future_api = future();
-    auto handle = future_api->SafeAlloc<StorageListResult>(kStorageReferenceFnListInternal);
-    ReturnedListResponse* response =
-        new ReturnedListResponse(handle, future_api, AsStorageReference());
+  auto send_request_funct{
+      [&, max_results_per_page, token_str]() -> BlockingResponse* {
+        auto* future_api = future();
+        auto handle = future_api->SafeAlloc<StorageListResult>(
+            kStorageReferenceFnListInternal);
+        ReturnedListResponse* response =
+            new ReturnedListResponse(handle, future_api, AsStorageReference());
 
-    storage::internal::Request* request = new storage::internal::Request();
+        storage::internal::Request* request = new storage::internal::Request();
 
-    // NOTE: The backend expects the base url for list to be the bucket, not the object.
-    // So we reconstruct it.
-    std::string list_url = storage_->get_scheme();
-    list_url += "://";
-    list_url += storage_->get_host();
-    list_url += ":";
-    list_url += std::to_string(storage_->get_port());
-    list_url += "/v0/b/";
-    list_url += bucket();
-    list_url += "/o";
-
-    std::string path = storageUri_.GetPath().str();
-    if (!path.empty() && path.back() != '/') {
-        path += '/';
-    }
+        // NOTE: The backend expects the base url for list to be the bucket, not
+        // the object. So we reconstruct it.
+        std::string list_url = storage_->get_scheme();
+        list_url += "://";
+        list_url += storage_->get_host();
+        list_url += ":";
+        list_url += std::to_string(storage_->get_port());
+        list_url += "/v0/b/";
+        list_url += bucket();
+        list_url += "/o";
+
+        std::string path = storageUri_.GetPath().str();
+        if (!path.empty() && path.back() != '/') {
+          path += '/';
+        }
 
-    list_url += "?prefix=";
-    if (!path.empty()) {
-        list_url += rest::util::EncodeUrl(path);
-    }
-    list_url += "&delimiter=";
-    list_url += rest::util::EncodeUrl("/");
-    if (!token_str.empty()) {
-        list_url += "&pageToken=";
-        list_url += rest::util::EncodeUrl(token_str);
-    }
-    list_url += "&maxResults=";
-    list_url += std::to_string(max_results_per_page);
+        list_url += "?prefix=";
+        if (!path.empty()) {
+          list_url += rest::util::EncodeUrl(path);
+        }
+        list_url += "&delimiter=";
+        list_url += rest::util::EncodeUrl("/");
+        if (!token_str.empty()) {
+          list_url += "&pageToken=";
+          list_url += rest::util::EncodeUrl(token_str);
+        }
+        list_url += "&maxResults=";
+        list_url += std::to_string(max_results_per_page);
 
-    PrepareRequestBlocking(request, list_url.c_str(), rest::util::kGet);
+        PrepareRequestBlocking(request, list_url.c_str(), rest::util::kGet);
 
-    RestCall(request, request->notifier(), response, handle.get(), nullptr,
-             nullptr);
+        RestCall(request, request->notifier(), response, handle.get(), nullptr,
+                 nullptr);
 
-    return response;
-  }};
+        return response;
+      }};
 
-  SendRequestWithRetry(kStorageReferenceFnListInternal,
-                       send_request_funct, handle,
-                       storage_->max_operation_retry_time());
+  SendRequestWithRetry(kStorageReferenceFnListInternal, send_request_funct,
+                       handle, storage_->max_operation_retry_time());
   return ListLastResult();
 }
 

storage/src/desktop/storage_reference_desktop.h

@@ -149,7 +149,7 @@ class StorageReferenceInternal {
 
   // List items (files) and prefixes (folders) under this StorageReference.
   Future<StorageListResult> List(int max_results_per_page,
-                                 const char *page_token);
+                                 const char* page_token);
 
   // Returns the result of the most recent call to List();
   Future<StorageListResult> ListLastResult();
@@ -194,7 +194,7 @@ class StorageReferenceInternal {
 
   // List operation without metadata.
   Future<StorageListResult> ListInternal(int max_results_per_page,
-                                         const char *page_token);
+                                         const char* page_token);
 
   void RestCall(rest::Request* request, internal::Notifier* request_notifier,
                 BlockingResponse* response, FutureHandle handle,

storage/src/include/firebase/storage/list_result.h

@@ -31,11 +31,17 @@ class StorageListResult {
  public:
   StorageListResult();
   ~StorageListResult();
+  /// @brief Copy constructor.
   StorageListResult(const StorageListResult& other);
+
+  /// @brief Copy assignment operator.
   StorageListResult& operator=(const StorageListResult& other);
 
 #if defined(FIREBASE_USE_MOVE_OPERATORS) || defined(DOXYGEN)
+  /// @brief Move constructor.
   StorageListResult(StorageListResult&& other);
+
+  /// @brief Move assignment operator.
   StorageListResult& operator=(StorageListResult&& other);
 #endif  // defined(FIREBASE_USE_MOVE_OPERATORS) || defined(DOXYGEN)