Skip to content

Python: Remove a stale Args block from a samples docstring - #10233

Open
Hyacinth-of-Security (lxcxjxhx) wants to merge 3 commits into
microsoft:mainfrom
lxcxjxhx:docs/remove-stale-stream-arg
Open

Hyacinth-of-Security (lxcxjxhx) wants to merge 3 commits into
microsoft:mainfrom
lxcxjxhx:docs/remove-stale-stream-arg

Conversation

@lxcxjxhx

Copy link
Copy Markdown
Contributor

Motivation & Context

run_chat_client() in python/samples/02-agents/observability/advanced_manual_setup_console_output.py takes no parameters:

async def run_chat_client() -> None:

but its docstring documents one:

    Args:
        stream: Whether to use streaming for the plugin

Nothing in the function reads stream, and "for the plugin" points at where the paragraph came from — a sibling plugin sample. Someone reading this file to learn how streaming is enabled will look for the parameter, not find it, and have to decide whether the sample is stale or they opened the wrong overload.

Description & Review Guide

  • What are the major changes? Three lines removed from one docstring: the Args: heading, the stream: entry, and the blank line that separated it from Remarks:.
  • What is the impact of these changes? None at runtime. The rest of the docstring — the summary, the telemetry paragraphs, and the Remarks: block — is untouched.
  • What do you want reviewers to focus on? Whether removing the block is the right call versus adding the parameter. I read the function body and found no stream usage and no streaming branch, so documenting it seemed like the smaller fix than inventing behaviour; if the intent was that this sample should demonstrate streaming, the parameter is the thing to add and I can do that instead.

Related Issue

N/A - trivial change

AI Assistance

  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

Assisted areas: documentation. A scan of this repository's docstrings compared each Args: entry against the actual signature and reported this function as the single mismatch in python/ (1342 files). I read the function to confirm it takes no arguments and does not reference stream, and re-ran the same scan after the edit to confirm the mismatch count went from 1 to 0. The PR description and the commit message are mine.

`run_chat_client()` in `samples/02-agents/observability/advanced_manual_setup_console_output.py`
takes no parameters, but its docstring documents one:

    async def run_chat_client() -> None:
        """Run an AI service.
        ...
        Args:
            stream: Whether to use streaming for the plugin
        """

Nothing in the function reads `stream`, and the phrase "for the plugin" says where the
paragraph came from — a sibling sample. A reader who wants to turn streaming on will look
for the parameter, not find it, and have to decide whether the sample is out of date or they
are reading the wrong overload.

Removing the block leaves the rest of the docstring untouched; `Args:` is the only section
that described something absent.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for this docstring-only correction.

No open issues 🎉

What changed in this PR

Corrects the observability sample’s run_chat_client() docstring to match its parameterless signature.

Changes:

  • Removes the stale Args: block documenting an unused stream parameter.
  • Leaves runtime behavior and the remaining docstring unchanged.
File Description
python/​samples/​02-agents/​observability/​advanced_manual_setup_console_output.py Removes incorrect parameter documentation from run_chat_client().

Review effort: Balanced

This branch was successfully deployed

1 active deployment
github-app-auth — e018b260 Deployed Nov 10, 2026 by lxcxjxhx via add_label #27513
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants