Merge pull request #628 from microsoft/emolsh/api-ref-docs-activityprompt

emolsh/api-ref-docs-activityprompt

Author: tracyboehrer

libraries/botbuilder-dialogs/botbuilder/dialogs/prompts/activity_prompt.py

@@ -19,14 +19,19 @@
 from .prompt_recognizer_result import PromptRecognizerResult
 from .prompt_validator_context import PromptValidatorContext
 
-
 class ActivityPrompt(Dialog, ABC):
     """
     Waits for an activity to be received.
 
-    This prompt requires a validator be passed in and is useful when waiting for non-message
-    activities like an event to be received. The validator can ignore received events until the
-    expected activity is received.
+        .. remarks:
+            This prompt requires a validator be passed in and is useful when waiting for non-message
+            activities like an event to be received. The validator can ignore received events until the
+            expected activity is received.
+
+    :var persisted_options:
+    :typevar persisted_options: str
+    :var persisted_state:
+    :vartype persisted_state: str
     """
 
     persisted_options = "options"
@@ -36,13 +41,12 @@ def __init__(
         self, dialog_id: str, validator: Callable[[PromptValidatorContext], bool]
     ):
         """
-        Initializes a new instance of the ActivityPrompt class.
-
-        Parameters:
-        ----------
-        dialog_id (str): Unique ID of the dialog within its parent DialogSet or ComponentDialog.
+        Initializes a new instance of the :class:`ActivityPrompt` class.
 
-        validator: Validator that will be called each time a new activity is received.
+        :param dialog_id: Unique ID of the dialog within its parent :class:`DialogSet` or :class:`ComponentDialog`.
+        :type dialog_id: str
+        :param validator: Validator that will be called each time a new activity is received.
+        :type validator: Callable[[PromptValidatorContext], bool]
         """
         Dialog.__init__(self, dialog_id)
 
@@ -53,6 +57,16 @@ def __init__(
     async def begin_dialog(
         self, dialog_context: DialogContext, options: PromptOptions = None
     ) -> DialogTurnResult:
+        """
+        Called when a prompt dialog is pushed onto the dialog stack and is being activated.
+
+        :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`
+        :return Dialog.end_of_turn: 
+        :rtype Dialog.end_of_turn: :class:`Dialog.DialogTurnResult`
+        """
         if not dialog_context:
             raise TypeError("ActivityPrompt.begin_dialog(): dc cannot be None.")
         if not isinstance(options, PromptOptions):
@@ -84,6 +98,14 @@ async def begin_dialog(
 
     async def continue_dialog(self, dialog_context: DialogContext) -> DialogTurnResult:
         if not dialog_context:
+            """
+            Called when a prompt dialog is the active dialog and the user replied with a new activity.
+
+            :param dialog_context: The dialog context for the current turn of the conversation.
+            :type dialog_context: :class:`DialogContext`
+            :return Dialog.end_of_turn: 
+            :rtype Dialog.end_of_turn: :class:`Dialog.DialogTurnResult`
+            """
             raise TypeError(
                 "ActivityPrompt.continue_dialog(): DialogContext cannot be None."
             )
@@ -130,11 +152,22 @@ async def resume_dialog(  # pylint: disable=unused-argument
         self, dialog_context: DialogContext, reason: DialogReason, result: object = None
     ):
         """
-        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
-        resume_dialog() when the pushed on dialog ends.
-        To avoid the prompt prematurely ending, we need to implement this method and
-        simply re-prompt the user
+        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.
+        
+        .. note:
+            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 implement this method and
+            simply re-prompt the user.
+            
+        :param dialog_context: The dialog context for the current turn of the conversation
+        :type dialog_context: :class:`DialogContext`
+        :param reason: An enum indicating why the dialog resumed.
+        :type reason: :class:`DialogReason`
+        :param result: Optional, value returned from the previous dialog on the stack. 
+        :type result: object
         """
         await self.reprompt_dialog(dialog_context.context, dialog_context.active_dialog)
 
@@ -155,15 +188,14 @@ async def on_prompt(
         """
         Called anytime the derived class should send the user a prompt.
 
-        Parameters:
-        ----------
-        context: Context for the current turn of conversation with the user.
-
-        state: Additional state being persisted for the prompt.
-
-        options: Options that the prompt started with in the call to `DialogContext.prompt()`.
-
-        isRetry: If `true` the users response wasn't recognized and the re-prompt should be sent.
+        :param dialog_context: The dialog context for the current turn of the conversation
+        :type dialog_context: :class:`DialogContext`
+        :param state: Additional state being persisted for the prompt.
+        :type state: Dict[str, dict]
+        :param options: Options that the prompt started with in the call to `DialogContext.prompt()`.
+        :type options: :class:`PromptOptions`
+        :param isRetry: If `true` the users response wasn't recognized and the re-prompt should be sent.
+        :type isRetry: bool
         """
         if is_retry and options.retry_prompt:
             options.retry_prompt.input_hint = InputHints.expecting_input
@@ -175,7 +207,18 @@ async def on_prompt(
     async def on_recognize(  # pylint: disable=unused-argument
         self, context: TurnContext, state: Dict[str, object], options: PromptOptions
     ) -> PromptRecognizerResult:
-
+        """
+        When overridden in a derived class, attempts to recognize the incoming activity.
+
+        :param context: Context for the current turn of conversation with the user.
+        :type context: :class:`TurnContext`
+        :param state: Contains state for the current instance of the prompt on the dialog stack.
+        :type state: Dict[str, object]
+        :param options: A prompt options object
+        :type options: :class:`PromptOptions`
+        :return result: constructed from the options initially provided in the call to `async def on_prompt()`
+        :rtype result: :class:`PromptRecognizerResult`
+        """
         result = PromptRecognizerResult()
         result.succeeded = (True,)
         result.value = context.activity