Update / cleanup class and function comments, with a focus on bad cross references.

libraries/microsoft-agents-activity/microsoft_agents/activity/adaptive_card_invoke_value.py

@@ -10,9 +10,9 @@ class AdaptiveCardInvokeValue(AgentsModel):
     Defines the structure that arrives in the Activity.Value for Invoke activity with Name of 'adaptiveCard/action'.
 
     :param action: The action of this adaptive card invoke action value.
-    :type action: :class:`microsoft_agents.activity.models.AdaptiveCardInvokeAction`
+    :type action: :class:`microsoft_agents.activity.adaptive_card_invoke_action.AdaptiveCardInvokeAction`
     :param authentication: The TokenExchangeInvokeRequest for this adaptive card invoke action value.
-    :type authentication: :class:`microsoft_agents.activity.models.TokenExchangeInvokeRequest`
+    :type authentication: :class:`microsoft_agents.activity.token_exchange_invoke_request.TokenExchangeInvokeRequest`
     :param state: The 'state' or magic code for an OAuth flow.
     :type state: str
     """

libraries/microsoft-agents-activity/microsoft_agents/activity/semantic_action.py

@@ -8,9 +8,9 @@ class SemanticAction(AgentsModel):
     :param id: ID of this action
     :type id: str
     :param entities: Entities associated with this action
-    :type entities: dict[str, ~microsoft_agents.activity.Entity]
+    :type entities: dict[str, :class:`microsoft_agents.activity.entity.Entity`]
     :param state: State of this action. Allowed values: `start`, `continue`, `done`
-    :type state: str or ~microsoft_agents.activity.SemanticActionStates
+    :type state: str or :class:`microsoft_agents.activity.semantic_action_states.SemanticActionStates`
     """
 
     id: NonEmptyString

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/activity_handler.py

@@ -105,8 +105,7 @@ async def on_message_activity(  # pylint: disable=unused-argument
         such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -119,8 +118,7 @@ async def on_message_update_activity(  # pylint: disable=unused-argument
         such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -133,8 +131,7 @@ async def on_message_delete_activity(  # pylint: disable=unused-argument
         such as the conversational logic.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -146,7 +143,6 @@ async def on_conversation_update_activity(self, turn_context: TurnContextProtoco
 
         :param turn_context: The context object for this turn
         :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -179,10 +175,9 @@ async def on_members_added_activity(
 
         :param members_added: A list of all the members added to the conversation, as described by the
         conversation update activity
-        :type members_added: :class:`typing.List`
+        :type members_added: list[ChannelAccount]
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -201,10 +196,9 @@ async def on_members_removed_activity(
 
         :param members_added: A list of all the members removed from the conversation, as described by the
         conversation update activity
-        :type members_added: :class:`typing.List`
+        :type members_added: list[ChannelAccount]
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -265,10 +259,9 @@ async def on_reactions_added(  # pylint: disable=unused-argument
         are added to the conversation.
 
         :param message_reactions: The list of reactions added
-        :type message_reactions: :class:`typing.List`
+        :type message_reactions: list[MessageReaction]
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -291,9 +284,9 @@ async def on_reactions_removed(  # pylint: disable=unused-argument
         are removed from the conversation.
 
         :param message_reactions: The list of reactions removed
-        :type message_reactions: :class:`typing.List`
+        :type message_reactions: list[MessageReaction]
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
 
         :returns: A task that represents the work queued to execute
 
@@ -312,8 +305,7 @@ async def on_event_activity(self, turn_context: TurnContextProtocol):
         :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -343,8 +335,7 @@ async def on_token_response_event(  # pylint: disable=unused-argument
         If using an `oauth_prompt`, override this method to forward this activity to the current dialog.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -360,11 +351,8 @@ async def on_event(  # pylint: disable=unused-argument
         """
         Invoked when an event other than `tokens/response` is received when the base behavior of
         :meth:`on_event_activity()` is used.
-
-
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
-
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
 
         .. remarks::
@@ -379,9 +367,8 @@ async def on_end_of_conversation_activity(  # pylint: disable=unused-argument
     ):
         """
         Invoked when a conversation end activity is received from the channel.
-
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`microsoft_agents.builder.TurnContext`
+        :type turn_context: :class:`microsoft_agents.activity.TurnContextProtocol`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -522,7 +509,7 @@ async def on_adaptive_card_invoke(
         :param turn_context: A context object for this turn.
         :type turn_context: :class:`microsoft_agents.builder.TurnContext`
         :param invoke_value: A string-typed object from the incoming activity's value.
-        :type invoke_value: :class:`microsoft_agents.activity.models.AdaptiveCardInvokeValue`
+        :type invoke_value: :class:`microsoft_agents.activity.adaptive_card_invoke_value.AdaptiveCardInvokeValue`
         :return: The HealthCheckResponse object
         """
         raise _InvokeResponseException(HTTPStatus.NOT_IMPLEMENTED)

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_adapter.py

@@ -42,7 +42,7 @@ async def send_activities(
         :param context: The context object for the turn.
         :type context: :class:`TurnContext`
         :param activities: The activities to send.
-        :type activities: :class:`typing.List[Activity]`
+        :type activities: list[Activity]
         :return:
         """
         raise NotImplementedError()
@@ -102,7 +102,7 @@ async def continue_conversation(
         :param reference: A reference to the conversation to continue.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: :class:`typing.Callable`
+        :type callback: Callable[[TurnContext], Awaitable]
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
         :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
         :param audience:A value signifying the recipient of the proactive message.
@@ -128,7 +128,7 @@ async def continue_conversation_with_claims(
         :param continuation_activity: The activity to send.
         :type continuation_activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: :class:`typing.Callable`
+        :type callback: Callable[[TurnContext], Awaitable]
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         """
@@ -157,7 +157,7 @@ async def create_conversation(
         :param conversation_parameters: The information to use to create the conversation
         :type conversation_parameters: :class:`microsoft_agents.activity.models.ConversationParameters`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: :class:`typing.Callable[[TurnContext], Awaitable]`
+        :type callback: Callable[[TurnContext], Awaitable]
 
         :raises: Exception - Not implemented or when the implementation fails.
 
@@ -224,7 +224,7 @@ async def run_pipeline(
         :param context: The context object for the turn.
         :type context: :class:`TurnContext`
         :param callback: A callback method to run at the end of the pipeline.
-        :type callback: :class:`typing.Callable[[TurnContext], Awaitable]`
+        :type callback: Callable[[TurnContext], Awaitable]
         :return:
         """
         if context is None:

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_service_adapter.py

@@ -154,13 +154,13 @@ async def continue_conversation(  # pylint: disable=arguments-differ
         Most channels require a user to initiate a conversation with an agent before the agent can send activities
         to the user.
 
-        :param reference: A reference to the conversation to continue.
-        :type reference: :class:`microsoft_agents.activity.ConversationReference`
-        :param callback: The method to call for the resulting agent turn.
-        :type callback: :class:`typing.Callable`
         :param agent_app_id: The application Id of the agent. This is the appId returned by the Azure portal registration,
-        and is generally found in the `MicrosoftAppId` parameter in `config.py`.
-        :type agent_app_id: :class:`typing.str`
+            and is generally found in the `MicrosoftAppId` parameter in `config.py`.
+        :type agent_app_id: str
+        :param continuation_activity: The activity to continue the conversation with.
+        :type continuation_activity: Activity
+        :param callback: The method to call for the resulting agent turn.
+        :type callback: Callable[[TurnContext], Awaitable]
         """
         if not callable:
             raise TypeError(
@@ -304,11 +304,11 @@ async def process_activity(
         Creates a turn context and runs the middleware pipeline for an incoming activity.
 
         :param auth_header: The HTTP authentication header of the request
-        :type auth_header: :class:`typing.Union[typing.str, AuthenticateRequestResult]`
+        :type auth_header: Union[str, AuthenticateRequestResult]
         :param activity: The incoming activity
-        :type activity: :class:`Activity`
+        :type activity: Activity
         :param callback: The callback to execute at the end of the adapter's middleware pipeline.
-        :type callback: :class:`typing.Callable`
+        :type callback: Callable[[TurnContext], Awaitable]
 
         :return: A task that represents the work queued to execute.
 
@@ -318,7 +318,7 @@ async def process_activity(
             agent *reactive messaging* flow.
             Call this method to reactively send a message to a conversation.
             If the task completes successfully, then an :class:`InvokeResponse` is returned;
-            otherwise. `null` is returned.
+            otherwise, `null` is returned.
         """
         scopes: list[str] = None
         outgoing_audience: str = None