Fix: Address review comments for List/ListAll stubs

This commit incorporates fixes based on code review feedback for the
stubbed StorageReference::List() and StorageReference::ListAll() methods
and the ListResult class implementation.

Key changes include:

1.  **PIMPL Pattern for `List` and `ListAll` Methods**:
    - The core logic for `List()` and `ListAll()`, including Future
      creation and `ListResultInternal` PIMPL instantiation, has been
      moved from common `StorageReference` code into the platform-specific
      `StorageReferenceInternal` classes (Desktop, Android, iOS).
    - Public `StorageReference::List()` and `StorageReference::ListAll()`
      now correctly delegate to these internal methods.

2.  **Doxygen Documentation**:
    - Added comprehensive Doxygen comments for `ListResult::items()`,
      `ListResult::prefixes()`, `ListResult::page_token()`, and
      `ListResult::is_valid()` in
      `storage/src/include/firebase/storage/list_result.h`, addressing
      previous warnings.

3.  **Method Naming Correction**:
    - Renamed the static helper method
      `ListResultInternalCommon::DeleteInternalPimpl` to
      `ListResultInternalCommon::DeleteInternal` in
      `storage/src/common/list_result.cc` and updated its call sites
      for consistency.

4.  **Comment Cleanup and Correction**:
    - Reverted an unintentional change to a pre-existing comment in
      `storage/src/common/storage_reference.cc`.
    - Removed various extraneous or outdated comments from:
        - `storage/src/ios/storage_reference_ios.h`
        - `storage/src/android/storage_reference_android.cc`
        - `storage/src/android/storage_reference_android.h`
    - A previously flagged comment in `storage/src/ios/storage_reference_ios.mm`
      was re-verified and found to be a necessary include with an
      accurate comment after architectural changes.

These changes address the specific points raised in the code review,
improving code structure, documentation, and cleanliness.

Author: google-labs-jules[bot]

storage/src/android/storage_reference_android.cc

@@ -26,8 +26,6 @@
 #include "storage/src/android/list_result_android.h" // Defines the android internal::ListResultInternal
 #include "storage/src/android/metadata_android.h"
 #include "storage/src/android/storage_android.h"
-// firebase/storage/storage_reference.h is included via storage_reference_android.h
-// app/src/future_manager.h is included via storage_reference_android.h -> reference_counted_future_impl.h
 #include "storage/src/include/firebase/storage.h"
 #include "storage/src/include/firebase/storage/common.h"
 #include "storage/storage_resources.h"

storage/src/android/storage_reference_android.h

@@ -24,7 +24,7 @@
 #include "app/src/util_android.h"
 #include "storage/src/android/storage_android.h"
 #include "storage/src/include/firebase/storage/storage_reference.h"
-#include "firebase/storage/list_result.h" // Added for ListResult return type
+#include "firebase/storage/list_result.h"
 
 namespace firebase {
 namespace storage {

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

@@ -59,25 +59,28 @@ class SWIG_STORAGE_EXPORT ListResult {
   /// @brief Destructor.
   ~ListResult();
 
-  /// @brief Gets the list of items (files) found by the list operation.
-  /// @return A const reference to a vector of StorageReferences representing
-  ///         the items. Returns an empty vector if the ListResult is invalid
-  ///         or no items were found.
+  /// @brief Gets the individual items (files) found in this result.
+  ///
+  /// @return Vector of StorageReferences to the items. Will be an empty
+  /// vector if no items are found or if the ListResult is invalid.
   const std::vector<StorageReference>& items() const;
 
-  /// @brief Gets the list of prefixes (directories) found by the list
-  /// operation.
-  /// These can be used to further navigate the storage hierarchy.
-  /// @return A const reference to a vector of StorageReferences representing
-  ///         the prefixes. Returns an empty vector if the ListResult is invalid
-  ///         or no prefixes were found.
+  /// @brief Gets the prefixes (directories) found in this result.
+  /// These can be used to further "navigate" the storage hierarchy by calling
+  /// List or ListAll on them.
+  ///
+  /// @return Vector of StorageReferences to the prefixes. Will be an empty
+  /// vector if no prefixes are found or if the ListResult is invalid.
   const std::vector<StorageReference>& prefixes() const;
 
   /// @brief Gets the page token for the next page of results.
+  ///
   /// If the string is empty, it indicates that there are no more results
-  /// (i.e., this is the last page).
-  /// @return A const reference to the page token string. Returns an empty
-  ///         string if the ListResult is invalid or if there are no more results.
+  /// for the current list operation. This token can be passed to
+  /// StorageReference::List() to retrieve the next page.
+  ///
+  /// @return Page token string. Empty if no more results or if the
+  /// ListResult is invalid.
   const std::string& page_token() const;
 
   /// @brief Returns true if this ListResult object is valid, false otherwise.