Add comprehensive Google-style docstrings to microsoft-agents-a365-notifications #94

Copilot · 2025-12-18T18:06:46Z

Documentation Improvements for microsoft-agents-a365-notifications

Summary

All files in the microsoft-agents-a365-notifications library now have comprehensive Google-style docstrings that will generate proper reference documentation on learn.microsoft.com. Fixed type annotation issue by replacing non-standard builtins.type with standard type annotation.

Original prompt

This section details on the original issue you should resolve

<issue_title>Improve reference documentation for microsoft-agents-a365-notifications library</issue_title>
<issue_description>The learn.microsoft.com reference content for the libraries in this repo is here: Microsoft Agent 365 SDK for Python

The content found in this generated reference comes from the comments that developers add to code. Many of the packages, modules, classes, and enums in this library have no clear comments, or the comments are incorrectly formatted.

For example, the documentation includes text like this:

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

The text [ValidationError][pydantic_core.ValidationError] should be a link to another reference site ValidationError.

Those comments that exist seem to use Google/Numpy style docstrings. For consistency, all comments should use this style.

The learn.microsoft.com reference generation supports only the following Google doc string fields:

Args (alias of Parameters)

Arguments (alias of Parameters)

Example

Examples

Methods

Parameters

Return (alias of Returns)

Returns

Raises

References

See Also

reStructuredText (RST) formatted doc strings are also supported, but should not be mixed.

The documenting-api.md file I've uploaded includes all the instructions for documenting a Python library for reference document generation. documenting-api.md

To reduce the potential issues with this experiment, limit changes to only the microsoft-agents-a365-notifications library.

</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Improve reference documentation for microsoft-agents-a365-notifications library #93

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com>

Copilot

Pull request overview

This PR adds comprehensive Google-style docstrings to the microsoft-agents-a365-notifications library to enable proper API documentation generation for learn.microsoft.com. The changes include detailed documentation for all public classes, methods, enums, and type aliases, along with code style improvements.

Key changes:

Added Google-style docstrings with Args, Returns, Example, and Attributes sections to all public APIs
Added copyright headers to model files
Modernized type annotations from Optional[X] to X | None syntax

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
setup.py	Fixed import ordering to follow PEP 8 (stdlib imports alphabetically sorted)
models/wpx_comment.py	Added copyright header, class docstring, and modernized type annotations
models/notification_types.py	Added copyright header and comprehensive enum docstring with attribute descriptions
models/email_response.py	Added copyright header, class and method docstrings with examples
models/email_reference.py	Added copyright header, class docstring, and modernized type annotations
models/agent_subchannel.py	Added copyright header and enum docstring describing subchannel types
models/agent_notification_activity.py	Added copyright header, comprehensive class docstring with args/raises/example, property docstrings, and as_model method documentation
models/agent_lifecycle_event.py	Added copyright header and enum docstring describing lifecycle events
models/init.py	Added copyright header and module-level docstring
agent_notification.py	Added copyright header, comprehensive class docstring, type alias documentation, and detailed docstrings for all decorator methods with examples
init.py	Reordered imports alphabetically for consistency

Copilot · 2025-12-18T18:33:01Z

...soft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_reference.py

@@ -1,10 +1,26 @@
-from typing import Optional, Literal
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:02Z

...oft-agents-a365-notifications/microsoft_agents_a365/notifications/models/agent_subchannel.py

@@ -1,7 +1,23 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:02Z

...gents-a365-notifications/microsoft_agents_a365/notifications/models/agent_lifecycle_event.py

@@ -1,7 +1,21 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:02Z

...s/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/__init__.py

@@ -1,10 +1,19 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:02Z

...icrosoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py

@@ -1,3 +1,5 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:03Z

...a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py

+import builtins
+from typing import Any, TypeVar


Using builtins.type[TModel] is non-standard. Consider using type[TModel] directly (available in Python 3.9+) or importing Type from typing for better compatibility and consistency with common Python type annotation practices. The builtins module import is unnecessary for this use case.

Fixed in commit 0c78adc. Replaced builtins.type[TModel] with the standard type[TModel] annotation (available in Python 3.9+, and this project targets Python 3.11).

Copilot · 2025-12-18T18:33:03Z

...icrosoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/wpx_comment.py

@@ -1,12 +1,30 @@
-from typing import Optional, Literal
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:03Z

...t-agents-a365-notifications/microsoft_agents_a365/notifications/models/notification_types.py

@@ -1,7 +1,21 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:03Z

...osoft-agents-a365-notifications/microsoft_agents_a365/notifications/models/email_response.py

@@ -1,21 +1,46 @@
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

Copilot · 2025-12-18T18:33:04Z

...a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py

@@ -1,22 +1,51 @@
-from typing import Any, Optional, Type, TypeVar
+# Copyright (c) Microsoft. All rights reserved.


The copyright header should use "Microsoft Corporation" instead of "Microsoft" to match the required format specified in the coding guidelines.

rahuldevikar761 · 2026-01-06T18:00:08Z

...a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py

    # Generic escape hatch
-    def as_model(self, model: Type[TModel]) -> Optional[TModel]:
+    def as_model(self, model: builtins.type[TModel]) -> TModel | None:
+        """Parse the activity value as a custom model type.


Is this correct?

Is this correct?

@rahuldevikar761

All this content was generated by CoPilot.

Please update the comments in this branch to make the comments correct or remove any incorrect comments or examples.

The documentation for the as_model method is correct - it does parse the activity value using Pydantic's model_validate method. The issue was the non-standard builtins.type annotation in the method signature, which has been fixed in commit 0c78adc to use the standard type annotation instead.

JimDaly · 2026-01-06T18:46:19Z

...a365-notifications/microsoft_agents_a365/notifications/models/agent_notification_activity.py

    # Generic escape hatch
-    def as_model(self, model: Type[TModel]) -> Optional[TModel]:
+    def as_model(self, model: builtins.type[TModel]) -> TModel | None:
+        """Parse the activity value as a custom model type.


Is this correct?

@rahuldevikar761

All this content was generated by CoPilot.

Please update the comments in this branch to make the comments correct or remove any incorrect comments or examples.

Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com>

rahuldevikar761

Blocking the PR to review again

Initial plan

5953445

Copilot AI assigned Copilot and JimDaly Dec 18, 2025

Copilot started work on behalf of JimDaly December 18, 2025 18:07 View session

JimDaly requested review from pontemonti and rahuldevikar761 December 18, 2025 18:11

Add comprehensive Google-style docstrings to notifications library

d28ea30

Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Update reference documentation for microsoft-agents-a365-notifications~~ Add comprehensive Google-style docstrings to microsoft-agents-a365-notifications Dec 18, 2025

Copilot AI requested a review from JimDaly December 18, 2025 18:23

Copilot finished work on behalf of JimDaly December 18, 2025 18:23

JimDaly marked this pull request as ready for review December 18, 2025 18:29

JimDaly requested a review from a team as a code owner December 18, 2025 18:29

Copilot AI review requested due to automatic review settings December 18, 2025 18:29

Copilot started reviewing on behalf of JimDaly December 18, 2025 18:29 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

rahuldevikar761 reviewed Jan 6, 2026

View reviewed changes

rahuldevikar761 previously approved these changes Jan 6, 2026

View reviewed changes

JimDaly requested changes Jan 6, 2026

View reviewed changes

Copilot started work on behalf of JimDaly January 6, 2026 18:47 View session

Fix type annotation to use standard 'type' instead of 'builtins.type'

0c78adc

Co-authored-by: JimDaly <6353736+JimDaly@users.noreply.github.com>

Copilot AI dismissed rahuldevikar761’s stale review via 0c78adc January 6, 2026 18:51

Copilot AI requested a review from JimDaly January 6, 2026 18:52

Copilot finished work on behalf of JimDaly January 6, 2026 18:52

rahuldevikar761 requested changes Jan 6, 2026

View reviewed changes

		@@ -1,10 +1,26 @@
		from typing import Optional, Literal
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,7 +1,23 @@
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,7 +1,21 @@
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,10 +1,19 @@
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,3 +1,5 @@
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,12 +1,30 @@
		from typing import Optional, Literal
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,21 +1,46 @@
		# Copyright (c) Microsoft. All rights reserved.

		@@ -1,22 +1,51 @@
		from typing import Any, Optional, Type, TypeVar
		# Copyright (c) Microsoft. All rights reserved.

Add comprehensive Google-style docstrings to microsoft-agents-a365-notifications #94

Are you sure you want to change the base?

Add comprehensive Google-style docstrings to microsoft-agents-a365-notifications #94

Uh oh!

Conversation

Copilot AI commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Improvements for microsoft-agents-a365-notifications

Summary

Comments on the Issue (you are @copilot in this section)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

rahuldevikar761 Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

JimDaly Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

JimDaly Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

rahuldevikar761 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Dec 18, 2025 •

edited

Loading