LCORE-946: updated utils doc

[tisnik]

Description

LCORE-946: updated utils doc

Type of change

• Refactor
• New feature
• Bug fix
• CVE fix
• Optimization
• Documentation Update
• Configuration Update
• Bump-up service version
• Bump-up dependent library
• Bump-up library or tool used for development (does not change the final image)
• CI configuration change
• Konflux configuration change
• Unit tests improvement
• Integration tests improvement
• End to end tests improvement

Related Tickets & Documents

• Related Issue #LCORE-946

Summary by CodeRabbit

• Documentation

  • Expanded docstrings for MCP server registration and initialization functions with comprehensive descriptions of behavior, parameter usage, error handling, and execution semantics.

• Refactor

  • Optimized control flow logic for improved efficiency during server initialization, particularly for edge cases with no configured servers.

[coderabbitai]

Walkthrough

Documentation improvements and a minor control-flow optimization in utility functions. Expanded docstrings for MCP server registration and async execution functions, plus an early return when no MCP servers are configured.

Changes

Cohort / File(s)	Summary
Documentation and control-flow improvements src/utils/common.py	Added early return in register_mcp_servers_async for empty MCP server configuration. Expanded docstrings for register_mcp_servers_async, _register_mcp_toolgroups_async, run_once_async, and inner wrapper to document behavior, parameters, and error handling.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Early return logic should be verified to ensure no side effects on downstream operations
• Docstring accuracy for error propagation and async semantics should be confirmed

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title references a ticket (LCORE-946) but provides only a vague description ('updated utils doc') that doesn't convey specific details about what documentation was improved.	Consider making the title more specific about what was updated, e.g., 'LCORE-946: Expand docstrings for MCP server registration and utility functions' to better communicate the nature of the documentation changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

📝 Customizable high-level summaries are now available!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide custom instructions to shape the summary (bullet lists, tables, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example:

"Create a concise high-level summary as a bullet-point list. Then include a Markdown table showing lines added and removed by each contributing author."

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 41e89f6 and 6ba4935.

📒 Files selected for processing (1)

• src/utils/common.py (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: build-pr
• GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
• GitHub Check: e2e_tests (ci)
• GitHub Check: e2e_tests (azure)

🔇 Additional comments (3)

src/utils/common.py (3)

60-72: Well-documented internal function.

The expanded docstring clearly explains the MCP toolgroup registration logic, parameter usage, and error handling behavior.

---

96-104: Clear decorator documentation.

The docstring effectively explains the one-time execution semantics, Task caching mechanism, and event loop requirements.

---

109-117: Inner wrapper documentation added.

The wrapper function now has its own docstring explaining the caching behavior. While there's some overlap with the outer function's docstring, documenting the inner implementation is still helpful for code maintainability.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Resolve the contradiction about the logger parameter.

The Parameters section documents the logger parameter (lines 26-27), but the Notes section states it is "intentionally undocumented as a common service" (lines 31-32). This is contradictory.

Consider either:

• Removing the logger entry from the Parameters section if it's meant to be undocumented, or
• Removing or rewording the note in lines 31-32 to reflect that the logger is now documented

Apply this diff to remove the contradictory note:

-        logger: Logger instance.
         configuration: Configuration containing the `mcp_servers` list and
         `llama_stack` client mode.
 
     Notes:
-        - The `logger` parameter is used for debug/info logging and is
-          intentionally undocumented as a common service.
         - Exceptions from the LlamaStack client (network/errors during
           initialization or registration) are not caught here and will
           propagate to the caller.

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents

In src/utils/common.py around lines 25 to 32, the docstring contradicts itself
by documenting the `logger` parameter in Parameters (lines 26-27) while the
Notes (lines 31-32) say the logger is intentionally undocumented; remove the
Notes lines that claim the logger is undocumented so the docstring consistently
documents `logger`, or alternatively reword the Notes to acknowledge that
`logger` is documented; apply the change by deleting the two-note lines (or
updating their text) so the docstring is no longer contradictory.