mm-api-ref-fixes-r3.1

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

@@ -7,6 +7,15 @@
 
 
 class ActivityHandler:
+    """
+    Handles activities and should be subclassed.
+
+    .. remarks::
+        Derive from this class to handle particular activity types.
+        Yon can add pre and post processing of activities by calling the base class
+        in the derived class.
+    """
+
     async def on_turn(self, turn_context: TurnContext):
         """
         Called by the adapter (for example, :class:`BotFrameworkAdapter`) at runtime
@@ -22,8 +31,8 @@ async def on_turn(self, turn_context: TurnContext):
             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.
             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()`.
+            - Add logic to apply before the type-specific logic and before calling :meth:`on_turn()`.
+            - Add logic to apply after the type-specific logic after calling :meth:`on_turn()`.
         """
         if turn_context is None:
             raise TypeError("ActivityHandler.on_turn(): turn_context cannot be None.")
@@ -71,21 +80,22 @@ async def on_message_activity(  # pylint: disable=unused-argument
     async def on_conversation_update_activity(self, turn_context: TurnContext):
         """
         Invoked when a conversation update activity is received from the channel when the base behavior of
-        :meth:`ActivityHandler.on_turn()` is used.
+        :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
         :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:'ActivityHandler.on_turn()` method receives a conversation update activity, it calls this
+            When the :meth:`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,
-            it calls the  :meth:`ActivityHandler.on_members_added_activity()` method.
-            If the conversation update activity indicates that members other than the bot left the conversation,
-            it calls the  :meth:`ActivityHandler.on_members_removed_activity()`  method.
-            In a derived class, override this method to add logic that applies to all conversation update activities.
+            Also
+            - If the conversation update activity indicates that members other than the bot joined the conversation,
+            it calls the  :meth:`on_members_added_activity()` method.
+            - If the conversation update activity indicates that members other than the bot left the conversation,
+            it calls the  :meth:`on_members_removed_activity()`  method.
+            - In a derived class, override this method to add logic that applies to all conversation update activities.
             Add logic to apply before the member added or removed logic before the call to this base class method.
         """
         if (
@@ -120,7 +130,7 @@ async def on_members_added_activity(
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
+            When the :meth:`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.
         """
@@ -142,7 +152,7 @@ async def on_members_removed_activity(
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:'ActivityHandler.on_conversation_update_activity()` method receives a conversation
+            When the :meth:`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.
         """
@@ -152,7 +162,7 @@ async def on_members_removed_activity(
     async def on_message_reaction_activity(self, turn_context: TurnContext):
         """
         Invoked when an event activity is received from the connector when the base behavior of
-        :meth:'ActivityHandler.on_turn()` is used.
+        :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
         :type turn_context: :class:`botbuilder.core.TurnContext`
@@ -162,15 +172,18 @@ async def on_message_reaction_activity(self, turn_context: TurnContext):
         .. 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
             to is indicated in the reply to Id property. The value of this property is the activity id of a previously
             sent activity given back to the bot as the response from a send call.
-            When the :meth:'ActivityHandler.on_turn()` method receives a message reaction activity, it calls this
+            When the :meth:`on_turn()` method receives a message reaction activity, it calls this
             method.
-            If the message reaction indicates that reactions were added to a message, it calls
-            :meth:'ActivityHandler.on_reaction_added().
-            If the message reaction indicates that reactions were removed from a message, it calls
-            :meth:'ActivityHandler.on_reaction_removed().
+
+            - If the message reaction indicates that reactions were added to a message, it calls
+            :meth:`on_reaction_added()`.
+            - If the message reaction indicates that reactions were removed from a message, it calls
+            :meth:`on_reaction_removed()`.
+
             In a derived class, override this method to add logic that applies to all message reaction activities.
             Add logic to apply before the reactions added or removed logic before the call to the this base class
             method.
@@ -202,8 +215,9 @@ async def on_reactions_added(  # pylint: disable=unused-argument
 
         .. 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.
+            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.
             The value of this property is the activity ID of a previously sent activity. When the bot sends an activity,
             the channel assigns an ID to it, which is available in the resource response Id of the result.
         """
@@ -235,17 +249,17 @@ async def on_reactions_removed(  # pylint: disable=unused-argument
     async def on_event_activity(self, turn_context: TurnContext):
         """
         Invoked when an event activity is received from the connector when the base behavior of
-        :meth:'ActivityHandler.on_turn()` is used.
+        :meth:`on_turn()` is used.
 
         :param turn_context: The context object for this turn
         :type turn_context: :class:`botbuilder.core.TurnContext`
 
         :returns: A task that represents the work queued to execute
 
         .. 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()`.
+            When the :meth:`on_turn()` method receives an event activity, it calls this method.
+            If the activity name is `tokens/response`, it calls :meth:`on_token_response_event()`;
+            otherwise, it calls :meth:`on_event()`.
 
             In a derived class, override this method to add logic that applies to all event activities.
             Add logic to apply before the specific event-handling logic before the call to this base class method.
@@ -265,7 +279,7 @@ async def on_token_response_event(  # pylint: disable=unused-argument
     ):
         """
         Invoked when a `tokens/response` event is received when the base behavior of
-        :meth:'ActivityHandler.on_event_activity()` is used.
+        :meth:`on_event_activity()` is used.
         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
@@ -274,7 +288,7 @@ async def on_token_response_event(  # pylint: disable=unused-argument
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:'ActivityHandler.on_event()` method receives an event with an activity name of
+            When the :meth:`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.
         """
@@ -285,7 +299,7 @@ async def on_event(  # pylint: disable=unused-argument
     ):
         """
         Invoked when an event other than `tokens/response` is received when the base behavior of
-        :meth:'ActivityHandler.on_event_activity()` is used.
+        :meth:`on_event_activity()` is used.
 
 
         :param turn_context: The context object for this turn
@@ -294,7 +308,7 @@ async def on_event(  # pylint: disable=unused-argument
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:'ActivityHandler.on_event_activity()` is used method receives an event with an
+            When the :meth:`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.
         """
@@ -317,7 +331,7 @@ async def on_unrecognized_activity_type(  # pylint: disable=unused-argument
     ):
         """
         Invoked when an activity other than a message, conversation update, or event is received when the base
-        behavior of :meth:`ActivityHandler.on_turn()` is used.
+        behavior of :meth:`on_turn()` is used.
         If overridden, this method could potentially respond to any of the other activity types.
 
         :param turn_context: The context object for this turn
@@ -326,7 +340,7 @@ async def on_unrecognized_activity_type(  # pylint: disable=unused-argument
         :returns: A task that represents the work queued to execute
 
         .. remarks::
-            When the :meth:`ActivityHandler.on_turn()` method receives an activity that is not a message,
+            When the :meth:`on_turn()` method receives an activity that is not a message,
             conversation update, message reaction, or event activity, it calls this method.
         """
         return

libraries/botbuilder-core/botbuilder/core/bot_state.py

@@ -63,7 +63,7 @@ def __init__(self, storage: Storage, context_service_key: str):
 
     def create_property(self, name: str) -> StatePropertyAccessor:
         """
-        Create a property definition and register it with this :class:`BotState`.
+        Creates a property definition and registers it with this :class:`BotState`.
 
         :param name: The name of the property
         :type name: str
@@ -84,7 +84,7 @@ async def load(self, turn_context: TurnContext, force: bool = False) -> None:
         Reads the current state object and caches it in the context object for this turn.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         :param force: Optional, true to bypass the cache
         :type force: bool
         """
@@ -107,7 +107,7 @@ async def save_changes(
         If the state has changed, it saves the state cached in the current context for this turn.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         :param force: Optional, true to save state to storage whether or not there are changes
         :type force: bool
         """
@@ -127,7 +127,7 @@ async def clear_state(self, turn_context: TurnContext):
         Clears any state currently stored in this state scope.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
 
         :return: None
 
@@ -147,7 +147,7 @@ async def delete(self, turn_context: TurnContext) -> None:
         Deletes any state currently stored in this state scope.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
 
         :return: None
         """
@@ -168,7 +168,7 @@ async def get_property_value(self, turn_context: TurnContext, property_name: str
         Gets the value of the specified property in the turn context.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         :param property_name: The property name
         :type property_name: str
 
@@ -195,7 +195,7 @@ async def delete_property_value(
         Deletes a property from the state cache in the turn context.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :TurnContext`
         :param property_name: The name of the property to delete
         :type property_name: str
 
@@ -215,7 +215,7 @@ async def set_property_value(
         Sets a property to the specified value in the turn context.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         :param property_name: The property name
         :type property_name: str
         :param value: The value to assign to the property
@@ -252,10 +252,7 @@ def __init__(self, bot_state: BotState, name: str):
     @property
     def name(self) -> str:
         """
-        Gets the name of the property.
-
-        :return: The name of the property
-        :rtype: str
+        The name of the property.
         """
         return self._name
 
@@ -264,7 +261,7 @@ async def delete(self, turn_context: TurnContext) -> None:
         Deletes the property.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         """
         await self._bot_state.load(turn_context, False)
         await self._bot_state.delete_property_value(turn_context, self._name)
@@ -278,7 +275,7 @@ async def get(
         Gets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
         :param default_value_or_factory: Defines the default value for the property
         """
         await self._bot_state.load(turn_context, False)
@@ -303,7 +300,7 @@ async def set(self, turn_context: TurnContext, value: object) -> None:
         Sets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
 
         :param value: The value to assign to the property
         """

libraries/botbuilder-core/botbuilder/core/conversation_state.py

@@ -32,7 +32,7 @@ def get_storage_key(self, turn_context: TurnContext) -> object:
         Gets the key to use when reading and writing state to and from storage.
 
         :param turn_context: The context object for this turn.
-        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :type turn_context: :class:`TurnContext`
 
         :raise: :class:`TypeError` if the :meth:`TurnContext.activity` for the current turn is missing
         :class:`botbuilder.schema.Activity` channelId or conversation information or the conversation's

libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_reason.py

@@ -7,18 +7,18 @@ class DialogReason(Enum):
     """
     Indicates in which a dialog-related method is being called.
 
-    :var BeginCalled: A dialog is being started through a call to `DialogContext.begin()`.
+    :var BeginCalled: A dialog is being started through a call to :meth:`DialogContext.begin()`.
     :vartype BeginCalled: int
-    :var ContinueCalled: A dialog is being continued through a call to `DialogContext.continue_dialog()`.
+    :var ContinueCalled: A dialog is being continued through a call to :meth:`DialogContext.continue_dialog()`.
     :vartype ContinueCalled: int
-    :var EndCalled: A dialog ended normally through a call to `DialogContext.end_dialog()
+    :var EndCalled: A dialog ended normally through a call to :meth:`DialogContext.end_dialog()
     :vartype EndCalled: int
     :var ReplaceCalled: A dialog is ending because it's being replaced through a call to
-    `DialogContext.replace_dialog()`.
+    :meth:``DialogContext.replace_dialog()`.
     :vartype ReplacedCalled: int
-    :var CancelCalled: A dialog was cancelled as part of a call to `DialogContext.cancel_all_dialogs()`.
+    :var CancelCalled: A dialog was cancelled as part of a call to :meth:`DialogContext.cancel_all_dialogs()`.
     :vartype CancelCalled: int
-    :var NextCalled: A preceding step was skipped through a call to `WaterfallStepContext.next()`.
+    :var NextCalled: A preceding step was skipped through a call to :meth:`WaterfallStepContext.next()`.
     :vartype NextCalled: int
     """
 

libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_state.py

@@ -13,7 +13,6 @@ class DialogState:
     def __init__(self, stack: List[DialogInstance] = None):
         """
         Initializes a new instance of the :class:`DialogState` class.
-        The new instance is created with an empty dialog stack.
 
         :param stack: The state information to initialize the stack with.
         :type stack: :class:`typing.List[:class:`DialogInstance`]`
@@ -29,7 +28,7 @@ def dialog_stack(self):
         Initializes a new instance of the :class:`DialogState` class.
 
         :return: The state information to initialize the stack with.
-        :rtype: list
+        :rtype: :class:`typing.List[:class:`DialogInstance`]`
         """
         return self._dialog_stack