Conversation
There was a problem hiding this comment.
Pull request overview
Updates Python docstrings across dialogs, core hosting, and activity libraries to use fully qualified object names, to support Learn API reference generation.
Changes:
- Replace short-form
:class:,:meth:, and:attr:references with fully qualified names (e.g.,microsoft_agents.hosting.dialogs.WaterfallDialog). - Update return/parameter documentation to reference fully qualified types in prompts, dialogs, proactive, and activity APIs.
- Standardize doc references across core app/proactive builder APIs to qualified
:rtype:/:return:targets.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/waterfall_step_context.py | Fully qualifies dialog and method references in WaterfallStepContext docstrings. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/waterfall_dialog.py | Fully qualifies waterfall step context, end-of-turn, and method references. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/prompts/prompt_options.py | Fully qualifies prompt and choice prompt type references. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/prompts/confirm_prompt.py | Fully qualifies PromptCultureModels reference. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/prompts/choice_prompt.py | Fully qualifies reference to _default_choice_options. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/prompts/attachment_prompt.py | Fully qualifies Attachment type reference. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/prompts/activity_prompt.py | Fully qualifies prompt lifecycle method/type references and Dialog.end_of_turn. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/models/dialog_reason.py | Fully qualifies dialog context/step context method references in enum docs. |
| libraries/microsoft-agents-hosting-dialogs/microsoft_agents/hosting/dialogs/component_dialog.py | Fully qualifies component dialog and related method/type references. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/proactive.py | Fully qualifies proactive API references (methods, attrs, options). |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation_reference_builder.py | Fully qualifies fluent builder :rtype: references. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation_builder.py | Fully qualifies fluent builder :rtype: references. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/proactive/conversation.py | Fully qualifies conversation factory/method references. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/input_file.py | Fully qualifies InputFile references in downloader docs. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/app_options.py | Fully qualifies AgentApplication.proactive attribute reference. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/agent_application.py | Fully qualifies AgentApplication.add_route reference in route decorator docs. |
| libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/activity_handler.py | Fully qualifies ActivityHandler method references in docstrings/notes. |
| libraries/microsoft-agents-activity/microsoft_agents/activity/activity.py | Fully qualifies Activity references in factory method docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| :var EndCalled: A dialog ended normally through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.end_dialog` | ||
| :vartype EndCalled: int | ||
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:``DialogContext.replace_dialog()`. | ||
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:``microsoft_agents.hosting.dialogs.DialogContext.replace_dialog`. |
There was a problem hiding this comment.
The ReplaceCalled docstring line has malformed reST markup (:meth:``...) which will break Sphinx/DocFX parsing. Use a normal :meth: role with a single backtick pair around the fully qualified method reference.
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:``microsoft_agents.hosting.dialogs.DialogContext.replace_dialog`. | |
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.replace_dialog`. |
| :vartype EndCalled: int | ||
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:``DialogContext.replace_dialog()`. | ||
| :var ReplaceCalled: A dialog is ending and replaced through a call to :meth:``microsoft_agents.hosting.dialogs.DialogContext.replace_dialog`. | ||
| :vartype ReplacedCalled: int |
There was a problem hiding this comment.
:vartype ReplacedCalled: doesn't match the enum member name (ReplaceCalled). This should be corrected so the generated docs don't refer to a non-existent symbol.
| :vartype ReplacedCalled: int | |
| :vartype ReplaceCalled: int |
| Implementations should download any files referenced by the incoming activity and return a | ||
| list of :class:`InputFile` instances representing the downloaded content. | ||
| list of :class:`microsoft_agents.hosting.core.InputFile` instances representing the downloaded content. | ||
| """ |
There was a problem hiding this comment.
Docstring references microsoft_agents.hosting.core.InputFile, but the class is defined in this module and the :rtype: below already uses microsoft_agents.hosting.core.app.input_file.InputFile. Align these to a single fully qualified path (preferably the defining module path) to avoid broken/duplicate API reference entries.
| :param context: The turn context for the current request. | ||
| :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext` | ||
| :return: A list of downloaded :class:`InputFile` objects. | ||
| :return: A list of downloaded :class:`microsoft_agents.hosting.core.InputFile` objects. |
There was a problem hiding this comment.
The :return: type uses microsoft_agents.hosting.core.InputFile while :rtype: uses microsoft_agents.hosting.core.app.input_file.InputFile. Use the same fully qualified type in both fields so documentation tooling resolves the return type consistently.
| :return: A list of downloaded :class:`microsoft_agents.hosting.core.InputFile` objects. | |
| :return: A list of downloaded :class:`microsoft_agents.hosting.core.app.input_file.InputFile` objects. |
| When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used method receives an event with an | ||
| activity name other than `tokens/response`, it calls this method. |
There was a problem hiding this comment.
Grammar issue in the note: "When the ... is used method receives..." reads incorrectly and is likely missing the word "method" after the reference (and/or a comma). Adjust the sentence so it parses clearly in the generated reference docs.
| When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` is used method receives an event with an | |
| activity name other than `tokens/response`, it calls this method. | |
| When the :meth:`microsoft_agents.hosting.core.ActivityHandler.on_event_activity` method is used, it receives an event with an | |
| activity name other than `tokens/response` and calls this method. |
| Indicates in which a dialog-related method is being called. | ||
|
|
||
| :var BeginCalled: A dialog is being started through a call to :meth:`DialogContext.begin()`. | ||
| :var BeginCalled: A dialog is being started through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.begin`. |
There was a problem hiding this comment.
:meth: references microsoft_agents.hosting.dialogs.DialogContext.begin, but DialogContext only defines begin_dialog (no begin). Update the doc reference to the correct method name so API reference links resolve.
| :var BeginCalled: A dialog is being started through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.begin`. | |
| :var BeginCalled: A dialog is being started through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.begin_dialog`. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| :var BeginCalled: A dialog is being started through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.begin`. | ||
| :vartype BeginCalled: int | ||
| :var ContinueCalled: A dialog is being continued through a call to :meth:`DialogContext.continue_dialog()`. | ||
| :var ContinueCalled: A dialog is being continued through a call to :meth:`microsoft_agents.hosting.dialogs.DialogContext.continue_dialog`. |
There was a problem hiding this comment.
:var BeginCalled links to microsoft_agents.hosting.dialogs.DialogContext.begin, but DialogContext does not define a begin method (it defines begin_dialog). This will produce a broken API reference link; update the reference to the actual method name.
|
@phecke could you please check if copilot comments are accurate? |
Change all docstrings from using object short-form naming to the fully qualified name. This is required for generation of the Learn API reference.