RHCLOUD-47070 - Update documentation around how list_workspaces handles pagination

[lennysgarage]

https://redhat.atlassian.net/browse/RHCLOUD-47070

Summary by CodeRabbit

Release Notes

• Documentation
  • Added detailed documentation and practical examples demonstrating how to list workspaces with support for both lazy iteration and bulk materialization approaches.
  • Improved API documentation with comprehensive guidance on automatic pagination handling and optional continuation token parameters for resuming workspace enumeration.
  • Enhanced example code showing real-world usage patterns for consuming workspace data.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation and examples are added for the ListWorkspaces API. The README introduces a "Listing Workspaces" section with usage examples demonstrating lazy iteration and materialization into a List. The example code shows conversion of the iterable response using StreamSupport, and comprehensive Javadoc is added to the ListWorkspaces class describing pagination behavior.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added "Listing Workspaces" section documenting ListWorkspaces.listWorkspaces() with example code showing lazy iteration and materialization into a List via StreamSupport.stream() and Collectors.toList().
Example Implementation examples/src/main/java/org/project_kessel/examples/ListWorkspacesExample.java	Added imports and code demonstrating materialization of Iterable<StreamedListObjectsResponse> into an in-memory List and printing total count.
API Documentation kessel-sdk/src/main/java/org/project_kessel/api/rbac/v2/ListWorkspaces.java	Added comprehensive Javadoc to class and both method overloads, documenting automatic continuation-token pagination, lazy iteration behavior, and optional resumption via continuation token.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and accurately describes the main objective: updating documentation for how list_workspaces handles pagination, which is confirmed by changes to README, Javadoc, and example code.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@kessel-sdk/src/main/java/org/project_kessel/api/rbac/v2/ListWorkspaces.java`:
- Around line 28-33: The docs show two traversals using the same variable
`workspaces`, which will invoke a fresh paginated RPC each time because the
class returns a new WorkspaceListIterator (see WorkspaceListIterator/new
iterator creation); update the eager materialisation example in the class-level
Javadoc of ListWorkspaces to either create and use a fresh Iterable instance
(e.g., a new variable instead of reusing `workspaces`) or clearly state that the
example intentionally reuses the prior variable and will trigger a separate
traversal/RPC, so readers aren’t misled into thinking the same iterator is being
reused.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 76f008a2-2617-4333-8cb1-aff8577a849e

📥 Commits

Reviewing files that changed from the base of the PR and between 3a2cf32 and cc52e11.

📒 Files selected for processing (3)

• README.md
• examples/src/main/java/org/project_kessel/examples/ListWorkspacesExample.java
• kessel-sdk/src/main/java/org/project_kessel/api/rbac/v2/ListWorkspaces.java