diff --git a/libraries/botbuilder-core/botbuilder/core/activity_handler.py b/libraries/botbuilder-core/botbuilder/core/activity_handler.py
index cbe65ed73..cecab9205 100644
--- a/libraries/botbuilder-core/botbuilder/core/activity_handler.py
+++ b/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,7 +80,7 @@ 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`
@@ -79,13 +88,14 @@ async def on_conversation_update_activity(self, turn_context: 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,7 +249,7 @@ 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`
@@ -243,9 +257,9 @@ async def on_event_activity(self, turn_context: 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
diff --git a/libraries/botbuilder-core/botbuilder/core/bot_state.py b/libraries/botbuilder-core/botbuilder/core/bot_state.py
index 7d429d9df..3c6b79329 100644
--- a/libraries/botbuilder-core/botbuilder/core/bot_state.py
+++ b/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
         """
diff --git a/libraries/botbuilder-core/botbuilder/core/conversation_state.py b/libraries/botbuilder-core/botbuilder/core/conversation_state.py
index ffbec86b2..4605700f6 100644
--- a/libraries/botbuilder-core/botbuilder/core/conversation_state.py
+++ b/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
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_reason.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_reason.py
index 7c12e3032..471646e84 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_reason.py
+++ b/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
     """
 
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_state.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_state.py
index 5306540f8..a00c78701 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_state.py
+++ b/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
 
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_result.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_result.py
index 706dcc757..4dcc39e55 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_result.py
+++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_result.py
@@ -7,9 +7,6 @@
 class DialogTurnResult:
     """
     Result returned to the caller of one of the various stack manipulation methods.
-
-    Use :meth:`DialogContext.end_dialog()` to end a :class:`Dialog` and
-    return a result to the calling context.
     """
 
     def __init__(self, status: DialogTurnStatus, result: object = None):
@@ -37,14 +34,7 @@ def result(self):
         """
         Final result returned by a dialog that just completed.
 
-       .. remarks::
-           This will only be populated in certain cases:
-           * The bot calls :meth:`DialogContext.begin_dialog()` to start a new
-           dialog and the dialog ends immediately.
-           * The bot calls :meth:`DialogContext.continue_dialog()` and a dialog
-           that was active ends.
-
-    :return self._result: Final result returned by a dialog that just completed.
-    :rtype self._result: object
-    """
+        :return self._result: Final result returned by a dialog that just completed.
+        :rtype self._result: object
+        """
         return self._result
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_status.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_status.py
index b88cd359b..6d8b61e51 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_status.py
+++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/dialog_turn_status.py
@@ -5,7 +5,7 @@
 
 class DialogTurnStatus(Enum):
     """
-    Codes indicating the state of the dialog stack after a call to `DialogContext.continueDialog()`
+    Indicates in which a dialog-related method is being called.
 
     :var Empty: Indicates that there is currently nothing on the dialog stack.
     :vartype Empty: int
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/oauth_prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/oauth_prompt.py
index d593bfb2d..a8cd05048 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/oauth_prompt.py
+++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/oauth_prompt.py
@@ -74,11 +74,10 @@ def __init__(
         :type dialogId: str
         :param settings: Additional authentication settings to use with this instance of the prompt
         :type settings: :class:`OAuthPromptSettings`
-        :param validator: Optional, a :class:`PromptValidator` that contains additional, custom validation
-        for this prompt
+        :param validator: Optional, contains additional, custom validation for this prompt
         :type validator: :class:`PromptValidatorContext`
 
-        .. note::
+        .. remarks::
             The value of :param dialogId: must be unique within the :class:`DialogSet`or :class:`ComponentDialog`
             to which the prompt is added.
         """
@@ -103,11 +102,13 @@ async def begin_dialog(
         :param dialog_context: The dialog context for the current turn of the conversation
         :type dialog_context:  :class:`DialogContext`
         :param options: Optional, additional information to pass to the prompt being started
-        :type options: :class:PromptOptions
+        :type options: :class:`PromptOptions`
+
         :return: Dialog turn result
-        :rtype: :class:DialogTurnResult
+        :rtype: :class`:`DialogTurnResult`
+
+        .. remarks::
 
-        .. note::
             If the task is successful, the result indicates whether the prompt is still active after the turn
             has been processed.
         """
@@ -157,8 +158,9 @@ async def continue_dialog(self, dialog_context: DialogContext) -> DialogTurnResu
 
         :param dialog_context: The dialog context for the current turn of the conversation
         :type dialog_context:  :class:`DialogContext`
+
         :return: Dialog turn result
-        :rtype: :class:DialogTurnResult
+        :rtype: :class:`DialogTurnResult`
 
         .. remarks::
             If the task is successful, the result indicates whether the dialog is still
@@ -217,11 +219,12 @@ async def get_user_token(
         Gets the user's tokeN.
 
         :param context: Context for the current turn of conversation with the user
-        :type context:  :class:TurnContext
+        :type context:  :class:`TurnContext`
+
         :return: A response that includes the user's token
-        :rtype: :class:TokenResponse
+        :rtype: :class:`TokenResponse`
 
-        .. note::
+        .. remarks::
             If the task is successful and the user already has a token or the user successfully signs in,
             the result contains the user's token.
         """
@@ -242,11 +245,10 @@ async def sign_out_user(self, context: TurnContext):
         Signs out the user
 
         :param context: Context for the current turn of conversation with the user
-        :type context:  :class:`botbuilder.core.TurnContext`
-        :return: A :class:`Task` representing the work queued to execute
-        :rtype: :class:`Task`
+        :type context:  :class:`TurnContext`
+        :return: A task representing the work queued to execute
 
-        .. note::
+        .. reamarks::
             If the task is successful and the user already has a token or the user successfully signs in,
             the result contains the user's token.
         """
diff --git a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/prompt.py b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/prompt.py
index d0ab57084..268ede9ab 100644
--- a/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/prompt.py
+++ b/libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/prompt.py
@@ -24,15 +24,17 @@
 
 class Prompt(Dialog):
     """
+
     Defines the core behavior of prompt dialogs. Extends the :class:`Dialog` base class.
 
     .. remarks::
         When the prompt ends, it returns an object that represents the value it was prompted for.
-        Use :meth:`DialogSet.add()` or :meth:`ComponentDialog.add_dialog()` to add a prompt to a dialog set or
-        component dialog, respectively.
+        Use :meth:`DialogSet.add()` or :meth:`ComponentDialog.add_dialog()` to add a prompt to
+        a dialog set or component dialog, respectively.
+
         Use :meth:`DialogContext.prompt()` or :meth:`DialogContext.begin_dialog()` to start the prompt.
-        If you start a prompt from a :class:`WaterfallStep` in a :class:`WaterfallDialog`, then the prompt result
-        will be available in the next step of the waterfall.
+        If you start a prompt from a :class:`WaterfallStep` in a :class:`WaterfallDialog`, then the
+        prompt result will be available in the next step of the waterfall.
     """
 
     ATTEMPT_COUNT_KEY = "AttemptCount"
@@ -43,11 +45,10 @@ def __init__(self, dialog_id: str, validator: object = None):
         """
         Creates a new :class:`Prompt` instance.
 
-        :param dialog_id: Unique Id of the prompt within its parent :class:`DialogSet` or
-        :class:`ComponentDialog`.
+        :param dialog_id: Unique Id of the prompt within its parent :class:`DialogSet`
+        :class:`ComponentDialog`
         :type dialog_id: str
-        :param validator: Optional custom validator used to provide additional validation and re-prompting
-        logic for the prompt.
+        :param validator: Optionally provide additional validation and re-prompting logic
         :type validator: Object
         """
         super(Prompt, self).__init__(dialog_id)
@@ -68,8 +69,7 @@ async def begin_dialog(
         :rtype: :class:`DialogTurnResult`
 
         .. note::
-            If the task is successful, the result indicates whether the prompt is still active
-            after the turn has been processed.
+            The result indicates whether the prompt is still active after the turn has been processed.
         """
         if not dialog_context:
             raise TypeError("Prompt(): dc cannot be None.")
@@ -99,7 +99,7 @@ async def begin_dialog(
 
     async def continue_dialog(self, dialog_context: DialogContext):
         """
-        Continues a dialog. Called when a prompt dialog is the active dialog and the user replied with a new activity.
+        Continues a dialog.
 
         :param dialog_context: The dialog context for the current turn of the conversation
         :type dialog_context:  :class:`DialogContext`
@@ -107,8 +107,11 @@ async def continue_dialog(self, dialog_context: DialogContext):
         :rtype: :class:`DialogTurnResult`
 
         .. remarks::
-            If the task is successful, the result indicates whether the dialog is still
-            active after the turn has been processed by the dialog.
+            Called when a prompt dialog is the active dialog and the user replied with a new activity.
+
+            If the task is successful, the result indicates whether the dialog is still active after
+            the turn has been processed by the dialog.
+
             The prompt generally continues to receive the user's replies until it accepts the
             user's reply as valid input for the prompt.
         """
@@ -150,13 +153,13 @@ async def resume_dialog(
         self, dialog_context: DialogContext, reason: DialogReason, result: object
     ) -> DialogTurnResult:
         """
-        Resumes a dialog. C
+        Resumes a dialog.
+
         :param dialog_context: The dialog context for the current turn of the conversation.
-        :type dialog_context:  :class:DialogContext
+        :type dialog_context:  :class:`DialogContext`
         :param reason: An enum indicating why the dialog resumed.
-        :type reason:  :class:DialogReason
+        :type reason:  :class:`DialogReason`
         :param result: Optional, value returned from the previous dialog on the stack.
-        The type of the value returned is dependent on the previous dialog.
         :type result:  object
         :return: The dialog turn result
         :rtype: :class:`DialogTurnResult`
@@ -164,26 +167,30 @@ async def resume_dialog(
         .. remarks::
             Called when a prompt dialog resumes being the active dialog on the dialog stack,
             such as when the previous active dialog on the stack completes.
+
             If the task is successful, the result indicates whether the dialog is still
             active after the turn has been processed by the dialog.
+
             Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs
             on top of the stack which will result in the prompt receiving an unexpected call to
             :meth:resume_dialog() when the pushed on dialog ends.
-            To avoid the prompt prematurely ending we need to simply re-prompt the user.
+
+            Simply re-prompt the user to avoid that the prompt ends prematurely.
+
         """
         await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog)
         return Dialog.end_of_turn
 
     async def reprompt_dialog(self, context: TurnContext, instance: DialogInstance):
         """
-        Reprompts user for input. Called when a prompt dialog has been requested to re-prompt the user for input.
+        Reprompts user for input.
 
         :param context: Context for the current turn of conversation with the user
-        :type context:  :class:TurnContext
+        :type context:  :class:`botbuilder.core.TurnContext`
         :param instance: The instance of the dialog on the stack
-        :type instance:  :class:DialogInstance
-        :return: A :class:Task representing the asynchronous operation
-        :rtype: :class:Task
+        :type instance:  :class:`DialogInstance`
+        :return: A task representing the asynchronous operation
+
         """
         state = instance.state[self.persisted_state]
         options = instance.state[self.persisted_options]
@@ -203,16 +210,15 @@ async def on_prompt(
         :param turn_context: Context for the current turn of conversation with the user
         :type turn_context:  :class:`botbuilder.core.TurnContext`
         :param state: Contains state for the current instance of the prompt on the dialog stack
-        :type state:  :class:Dict
+        :type state:  :class:`Dict`
         :param options: A prompt options object constructed from the options initially provided
-        in the call :meth:`DialogContext.prompt(self, dialog_id: str, options)`
+        in the call :meth:`DialogContext.prompt()`
         :type options:  :class:`PromptOptions`
-        :param is_retry: true if this is the first time this prompt dialog instance on the stack is prompting
-        the user for input; otherwise, false
+        :param is_retry: true if is the first time the user for input; otherwise, false
         :type is_retry:  bool
 
-        :return: A :class:Task representing the asynchronous operation.
-        :rtype: :class:Task
+        :return: A task representing the asynchronous operation.
+
         """
 
     @abstractmethod
@@ -223,18 +229,20 @@ async def on_recognize(
         options: PromptOptions,
     ):
         """
-        Recognizes the user's input. When overridden in a derived class, attempts to recognize the user's input.
+        Recognizes the user's input.
 
         :param turn_context: Context for the current turn of conversation with the user
         :type turn_context:  :class:`botbuilder.core.TurnContext`
         :param state: Contains state for the current instance of the prompt on the dialog stack
-        :type state:  :class:Dict
+        :type state:  :class:`Dict`
         :param options: A prompt options object constructed from the options initially provided
-        in the call :meth:`DialogContext.prompt(self, dialog_id: str, options)`
-        :type options:  :class:PromptOptions
+        in the call to :meth:`DialogContext.prompt()`
+        :type options:  :class:`PromptOptions`
 
         :return: A task representing the asynchronous operation.
-        :rtype: :class:Task
+
+        .. note::
+            When overridden in a derived class, attempts to recognize the user's input.
         """
 
     def append_choices(
@@ -258,14 +266,15 @@ def append_choices(
         :type style:  :class:`ListStyle`
         :param: options: Optional formatting options to use when presenting the choices
         :type style: :class:`ChoiceFactoryOptions`
-        :return: A :class:Task representing the asynchronous operation
-        :rtype: :class:Task
+
+        :return: A task representing the asynchronous operation
 
         .. remarks::
             If the task is successful, the result contains the updated activity.
             When overridden in a derived class, appends choices to the activity when the user
             is prompted for input. This is an helper function to compose an output activity
             containing a set of choices.
+
         """
         # Get base prompt text (if any)
         text = prompt.text if prompt is not None and prompt.text else ""