Merge pull request #690 from microsoft/mm-api-ref-docs-fixes-wip

mm-api-ref-docs-fixes-wip

Author: tracyboehrer

libraries/botbuilder-core/botbuilder/core/activity_handler.py

@@ -13,20 +13,17 @@ async def on_turn(self, turn_context: TurnContext):
         in order to process an inbound :class:`botbuilder.schema.Activity`.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
         .. remarks::
             It calls other methods in this class based on the type of the activity to
             process, which allows a derived class to provide type-specific logic in a controlled way.
             In a derived class, override this method to add logic that applies to all activity types.
-
-            .. note::
-                - Add logic to apply before the type-specific logic and before the call to the
-                  :meth:`ActivityHandler.on_turn()` method.
-                - Add logic to apply after the type-specific logic after the call to the
-                  :meth:`ActivityHandler.on_turn()` method.
+            Also
+            - Add logic to apply before the type-specific logic and before calling :meth:`ActivityHandler.on_turn()`.
+            - Add logic to apply after the type-specific logic after calling :meth:`ActivityHandler.on_turn()`.
         """
         if turn_context is None:
             raise TypeError("ActivityHandler.on_turn(): turn_context cannot be None.")
@@ -65,10 +62,9 @@ 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:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
-
         """
         return
 
@@ -78,11 +74,11 @@ async def on_conversation_update_activity(self, turn_context: TurnContext):
         :meth:`ActivityHandler.on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_turn()` method receives a conversation update activity, it calls this
             method.
             If the conversation update activity indicates that members other than the bot joined the conversation,
@@ -119,11 +115,11 @@ async def on_members_added_activity(
         conversation update activity
         :type members_added: :class:`typing.List`
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
             update activity that indicates
             one or more users other than the bot are joining the conversation, it calls this method.
@@ -141,11 +137,11 @@ async def on_members_removed_activity(
         conversation update activity
         :type members_added: :class:`typing.List`
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
             update activity that indicates one or more users other than the bot are leaving the conversation,
             it calls this method.
@@ -159,11 +155,11 @@ async def on_message_reaction_activity(self, turn_context: TurnContext):
         :meth:'ActivityHandler.on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji) to a previously
             sent activity.
             Message reactions are only supported by a few channels. The activity that the message reaction corresponds
@@ -200,11 +196,11 @@ async def on_reactions_added(  # pylint: disable=unused-argument
         :param message_reactions: The list of reactions added
         :type message_reactions: :class:`typing.List`
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji)
             to a previously sent message on the conversation. Message reactions are supported by only a few channels.
             The activity that the message is in reaction to is identified by the activity's reply to Id property.
@@ -223,11 +219,11 @@ async def on_reactions_removed(  # pylint: disable=unused-argument
         :param message_reactions: The list of reactions removed
         :type message_reactions: :class:`typing.List`
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             Message reactions correspond to the user adding a 'like' or 'sad' etc. (often an emoji)
             to a previously sent message on the conversation. Message reactions are supported by only a few channels.
             The activity that the message is in reaction to is identified by the activity's reply to Id property.
@@ -242,11 +238,11 @@ async def on_event_activity(self, turn_context: TurnContext):
         :meth:'ActivityHandler.on_turn()` is used.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_turn()` method receives an event activity, it calls this method.
             If the activity name is `tokens/response`, it calls :meth:'ActivityHandler.on_token_response_event()`;
             otherwise, it calls :meth:'ActivityHandler.on_event()`.
@@ -273,11 +269,11 @@ 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:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_event()` method receives an event with an activity name of
             `tokens/response`, it calls this method. If your bot uses an `oauth_prompt`, forward the incoming
             activity to the current dialog.
@@ -293,11 +289,11 @@ async def on_event(  # pylint: disable=unused-argument
 
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:'ActivityHandler.on_event_activity()` is used method receives an event with an
             activity name other than `tokens/response`, it calls this method.
             This method could optionally be overridden if the bot is meant to handle miscellaneous events.
@@ -311,7 +307,7 @@ 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:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
         :returns: A task that represents the work queued to execute
         """
         return
@@ -325,11 +321,11 @@ async def on_unrecognized_activity_type(  # pylint: disable=unused-argument
         If overridden, this method could potentially respond to any of the other activity types.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             When the :meth:`ActivityHandler.on_turn()` method receives an activity that is not a message,
             conversation update, message reaction, or event activity, it calls this method.
         """

libraries/botbuilder-core/botbuilder/core/bot_framework_adapter.py

@@ -87,11 +87,9 @@ def __init__(
         """
         Contains the settings used to initialize a :class:`BotFrameworkAdapter` instance.
 
-        :param app_id: The bot application ID. This is the appId returned by the Azure portal registration, and is
-        the value of the `MicrosoftAppId` parameter in the `config.py` file.
+        :param app_id: The bot application ID.
         :type app_id: str
-        :param app_password: The bot application password. This is the password returned by the Azure portal
-        registration, and is
+        :param app_password: The bot application password.
         the value os the `MicrosoftAppPassword` parameter in the `config.py` file.
         :type app_password: str
         :param channel_auth_tenant: The channel tenant to use in conversation
@@ -201,7 +199,7 @@ async def continue_conversation(
 
         :return: A task that represents the work queued to execute.
 
-        .. note::
+        .. remarks::
             This is often referred to as the bots *proactive messaging* flow as it lets the bot proactively
             send messages to a conversation or user that are already in a communication.
             Scenarios such as sending notifications or coupons to a user are enabled by this function.
@@ -247,7 +245,7 @@ async def create_conversation(
 
         :return: A task representing the work queued to execute.
 
-        .. note::
+        .. remarks::
             To start a conversation, your bot must know its account information and the user's
             account information on that channel.
             Most channels only support initiating a direct message (non-group) conversation.
@@ -306,9 +304,7 @@ async def create_conversation(
 
     async def process_activity(self, req, auth_header: str, logic: Callable):
         """
-        Creates a turn context and runs the middleware pipeline for an incoming activity,
-        Processes an activity received by the bots web server. This includes any messages sent from a
-        user and is the method that drives what's often referred to as the bots *reactive messaging* flow.
+        Creates a turn context and runs the middleware pipeline for an incoming activity.
 
         :param req: The incoming activity
         :type req: :class:`typing.str`
@@ -317,15 +313,15 @@ async def process_activity(self, req, auth_header: str, logic: Callable):
         :param logic: The logic to execute at the end of the adapter's middleware pipeline.
         :type logic: :class:`typing.Callable`
 
-        :return: A task that represents the work queued to execute. If the activity type
-        was `Invoke` and the corresponding key (`channelId` + `activityId`) was found then
-        an :class:`InvokeResponse` is returned; otherwise, `null` is returned.
+        :return: A task that represents the work queued to execute.
 
-        .. note::
+        .. remarks::
+            This class processes an activity received by the bots web server. This includes any messages
+            sent from a user and is the method that drives what's often referred to as the
+            bots *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.
-
         """
         activity = await self.parse_request(req)
         auth_header = auth_header or ""
@@ -457,7 +453,7 @@ async def update_activity(self, context: TurnContext, activity: Activity):
 
         :return: A task that represents the work queued to execute
 
-        .. note::
+        .. remarks::
             If the activity is successfully sent, the task result contains
             a :class:`botbuilder.schema.ResourceResponse` object containing the ID that
             the receiving channel assigned to the activity.
@@ -490,6 +486,7 @@ async def delete_activity(
         :return: A task that represents the work queued to execute
 
         .. note::
+
             The activity_id of the :class:`botbuilder.schema.ConversationReference` identifies the activity to delete.
         """
         try:
@@ -565,7 +562,7 @@ async def delete_conversation_member(
         Deletes a member from the current conversation.
 
         :param context: The context object for the turn
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param member_id: The ID of the member to remove from the conversation
         :type member_id: str
 
@@ -603,7 +600,7 @@ async def get_activity_members(self, context: TurnContext, activity_id: str):
         Lists the members of a given activity.
 
         :param context: The context object for the turn
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param activity_id: (Optional) Activity ID to enumerate.
         If not specified the current activities ID will be used.
 
@@ -645,7 +642,7 @@ async def get_conversation_members(self, context: TurnContext):
         Lists the members of a current conversation.
 
         :param context: The context object for the turn
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
 
         :raises: An exception error
 
@@ -674,9 +671,7 @@ async def get_conversation_members(self, context: TurnContext):
 
     async def get_conversations(self, service_url: str, continuation_token: str = None):
         """
-        Lists the Conversations in which this bot has participated for a given channel server. The channel server
-        returns results in pages and each page will include a `continuationToken` that can be used to fetch the next
-        page of results from the server.
+        Lists the Conversations in which this bot has participated for a given channel server.
 
         :param service_url: The URL of the channel server to query. This can be retrieved from
         `context.activity.serviceUrl`
@@ -689,8 +684,10 @@ async def get_conversations(self, service_url: str, continuation_token: str = No
 
         :return: A task that represents the work queued to execute
 
-        .. note:: If the task completes successfully, the result contains a page of the members of the current
-        conversation.
+        .. remarks::
+        The channel server returns results in pages and each page will include a `continuationToken` that
+        can be used to fetch the next page of results from the server.
+        If the task completes successfully, the result contains a page of the members of the current conversation.
         This overload may be called from outside the context of a conversation, as only the bot's service URL and
         credentials are required.
         """
@@ -705,7 +702,7 @@ async def get_user_token(
         Attempts to retrieve the token for a user that's in a login flow.
 
         :param context: Context for the current turn of conversation with the user
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param connection_name: Name of the auth connection to use
         :type connection_name: str
         :param magic_code" (Optional) user entered code to validate
@@ -752,7 +749,7 @@ async def sign_out_user(
         Signs the user out with the token server.
 
         :param context: Context for the current turn of conversation with the user
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param connection_name: Name of the auth connection to use
         :type connection_name: str
         :param user_id: User id of user to sign out
@@ -781,13 +778,14 @@ async def get_oauth_sign_in_link(
         Gets the raw sign-in link to be sent to the user for sign-in for a connection name.
 
         :param context: Context for the current turn of conversation with the user
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param connection_name: Name of the auth connection to use
         :type connection_name: str
 
         :returns: A task that represents the work queued to execute
 
         .. note::
+
             If the task completes successfully, the result contains the raw sign-in link
         """
         self.check_emulating_oauth_cards(context)
@@ -814,7 +812,7 @@ async def get_token_status(
         Retrieves the token status for each configured connection for the given user.
 
         :param context: Context for the current turn of conversation with the user
-        :type context: :class:`TurnContext`
+        :type context: :class:`botbuilder.core.TurnContext`
         :param user_id: The user Id for which token status is retrieved
         :type user_id: str
         :param include_filter: (Optional) Comma separated list of connection's to include.
@@ -848,14 +846,11 @@ async def get_aad_tokens(
         Retrieves Azure Active Directory tokens for particular resources on a configured connection.
 
         :param context: Context for the current turn of conversation with the user
-        :type context: :class:`TurnContext`
-
+        :type context: :class:`botbuilder.core.TurnContext`
         :param connection_name: The name of the Azure Active Directory connection configured with this bot
         :type connection_name: str
-
         :param resource_urls: The list of resource URLs to retrieve tokens for
         :type resource_urls: :class:`typing.List`
-
         :returns: Dictionary of resource Urls to the corresponding :class:'botbuilder.schema.TokenResponse`
         :rtype: :class:`typing.Dict`
         """