Skip to content

Sample code not property formatted #182

@JimDaly

Description

@JimDaly

The reference documentation published on learn.microsoft.com includes samples that are provided using docstrings in the code in of this repo. The document generation supports three different styles of doc strings

While all three are supported, for consistency only one style should be used within the repo.

In this repo there are samples within the doc strings that don't follow any of these.

For example: /libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py#L46C5-L73C8 has this docstring:

"""Handler for agent notifications from Microsoft 365 applications.

    This class provides decorators for registering handlers that respond to notifications
    from various Microsoft 365 channels and subchannels. It supports routing based on
    channel ID, subchannel, and lifecycle events.

    Args:
        app: The application instance that will handle the routed notifications.
        known_subchannels: Optional iterable of recognized subchannels. If None,
            defaults to all values in the AgentSubChannel enum.
        known_lifecycle_events: Optional iterable of recognized lifecycle events. If None,
            defaults to all values in the AgentLifecycleEvent enum.

    Example:
        ```python
        from microsoft_agents.hosting import Application
        from microsoft_agents_a365.notifications import AgentNotification

        app = Application()
        notifications = AgentNotification(app)

        @notifications.on_email()
        async def handle_email(context, state, notification):
            email = notification.email
            if email:
                await context.send_activity(f"Received email: {email.id}")
        ```
    """

The triple backtick code fences used within this example doesn't align with any of the supported styles and will cause unusable, garbled strings to be published rather than the expected sample code.

Docstrings included in this repo should:

  • Use one of the supported docstring styles consistently
  • Update samples within those doc strings to remove the triple backtick code fences and align with the common style used.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions