Merge pull request #598 from microsoft/mm-api-ref-docs-prompt

mm-api-ref-docs-prompt

Author: tracyboehrer

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

@@ -23,30 +23,31 @@
 
 
 class Prompt(Dialog):
-    """ Prompts base class
-    Defines the core behavior of prompt dialogs. Extends `Dialog` base class.
+    """
+    Defines the core behavior of prompt dialogs. Extends the :class:`Dialog` base class.
 
     .. remarks:: 
-        When the prompt ends, it should return an object that represents the 
-        value that was prompted for.
-        Use `DialogSet.Add(Dialog)` or `ComponentDialog.AddDialog(Dialog)` to add a prompt 
-        to a dialog set or component dialog, respectively.
-        Use `DialogContext.PromptAsync(string, PromptOptions, CancellationToken)` or
-        `DialogContext.BeginDialogAsync(string, object, CancellationToken)` to start the prompt.
-        If you start a prompt from a `WaterfallStep` in a `WaterfallDialog`, then the prompt 
-        result will be available in the next step of the waterfall.
+        When the prompt ends, it returns an object that represents the value it was prompted for.
+        Use :method:`DialogSet.add()` or :method:`ComponentDialog.add_dialog()` to add a prompt to a dialog set or 
+        component dialog, respectively.
+        Use :method:`DialogContext.prompt()` or :meth:`DialogContext.begin_dialog()` to start the prompt.
+        .. note::
+            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"
     persisted_options = "options"
     persisted_state = "state"
 
     def __init__(self, dialog_id: str, validator: object = None):
-        """Creates a new Prompt instance
-        :param dialog_id: Unique ID of the prompt within its parent :class:DialogSet or
-        :class:ComponentDialog.
+        """
+        Creates a new :class:`Prompt` instance.
+
+        :param dialog_id: Unique Id of the prompt within its parent :class:`DialogSet` or
+        :class:`ComponentDialog`.
         :type dialog_id: str
         :param validator: Optional custom validator used to provide additional validation and re-prompting logic for the prompt.
-        :type validator: object
+        :type validator: Object
         """
         super(Prompt, self).__init__(dialog_id)
 
@@ -55,17 +56,17 @@ def __init__(self, dialog_id: str, validator: object = None):
     async def begin_dialog(
         self, dialog_context: DialogContext, options: object = None
     ) -> DialogTurnResult:
-        """ Starts a prompt dialog.
-        Called when a prompt dialog is pushed onto the dialog stack and is being activated.
+        """ 
+        Starts a prompt dialog. 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: object
-        :return: A :class:Task representing the asynchronous operation.
-        :rtype: :class:Task
+        :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: Object
+        :return: The dialog turn result
+        :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 by the prompt.
         """
@@ -96,16 +97,15 @@ async def begin_dialog(
         return Dialog.end_of_turn
 
     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.
-
-        :param dialog_context: The dialog context for the current turn of the conversation.
-        :type dialog_context:  :class:DialogContext    
+        """ 
+        Continues a dialog. Called when a prompt dialog is the active dialog and the user replied with a new activity.
 
-        :return: A :class:Task representing the asynchronous operation.
-        :rtype: :class:Task
+        :param dialog_context: The dialog context for the current turn of the conversation
+        :type dialog_context:  :class:`DialogContext`    
+        :return: The dialog turn result
+        :rtype: :class:`DialogTurnResult`
 
-        .. remarks:: 
+        .. note:: 
             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
@@ -148,21 +148,21 @@ async def continue_dialog(self, dialog_context: DialogContext):
     async def resume_dialog(
         self, dialog_context: DialogContext, reason: DialogReason, result: object
     ) -> DialogTurnResult:
-        """ Resumes a dialog. 
-        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.
+        """ 
+        Resumes a dialog. 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.
 
         :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.
-            The type of the value returned is dependent on the previous dialog.
+        :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: A :class:Task representing the asynchronous operation.
-        :rtype: :class:Task
+        :return: The dialog turn result
+        :rtype: :class:`DialogTurnResult`
 
-        .. remarks::
+        .. note::
             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
@@ -174,14 +174,14 @@ async def resume_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 reprompt the user for input.
+        """ 
+        Reprompts user for input. Called when a prompt dialog has been requested to re-prompt the user for input.
 
-        :param context: Context for the current turn of conversation with the user.
+        :param context: Context for the current turn of conversation with the user
         :type context:  :class:TurnContext    
-        :param instance: The instance of the dialog on the stack.
+        :param instance: The instance of the dialog on the stack
         :type instance:  :class:DialogInstance    
-        :return: A :class:Task representing the asynchronous operation.
+        :return: A :class:Task representing the asynchronous operation
         :rtype: :class:Task
         """
         state = instance.state[self.persisted_state]
@@ -196,18 +196,18 @@ async def on_prompt(
         options: PromptOptions,
         is_retry: bool,
     ):
-        """ Prompts user for input.
-        When overridden in a derived class, prompts the user for input.
+        """ 
+        Prompts user for input. When overridden in a derived class, prompts the user for input.
 
-        :param turn_context: Context for the current turn of conversation with the user.
-        :type turn_context:  :class:TurnContext    
-        :param state: Contains state for the current instance of the prompt on the dialog stack.
+        :param turn_context: Context for the current turn of conversation with the user
+        :type turn_context:  :class:`TurnContext`    
+        :param state: Contains state for the current instance of the prompt on the dialog stack
         :type state:  :class:Dict
         :param options: A prompt options object constructed from the options initially provided
-        in the call :meth:DialogContext.PromptAsync(string, PromptOptions, CancellationToken).
-        :type options:  :class:PromptOptions   
+        in the call :meth:`DialogContext.prompt(self, dialog_id: str, options)`
+        :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.
+        the user for input; otherwise, false
         :type is_retry:  bool  
 
         :return: A :class:Task representing the asynchronous operation.
@@ -222,15 +222,15 @@ async def on_recognize(
         state: Dict[str, object],
         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. When overridden in a derived class, attempts to recognize the user's input.
 
-        :param turn_context: Context for the current turn of conversation with the user.
-        :type turn_context:  :class:TurnContext    
-        :param state: Contains state for the current instance of the prompt on the dialog stack.
+        :param turn_context: Context for the current turn of conversation with the user
+        :type turn_context:  :class:`TurnContext`    
+        :param state: Contains state for the current instance of the prompt on the dialog stack
         :type state:  :class:Dict
         :param options: A prompt options object constructed from the options initially provided
-        in the call :meth:DialogContext.PromptAsync(string, PromptOptions, CancellationToken).
+        in the call :meth:`DialogContext.prompt(self, dialog_id: str, options)`
         :type options:  :class:PromptOptions   
 
         :return: A :class:Task representing the asynchronous operation.
@@ -246,24 +246,25 @@ def append_choices(
         style: ListStyle,
         options: ChoiceFactoryOptions = None,
     ) -> Activity:
-        """ Composes an output activity containing a set of choices.
+        """ 
+        Composes an output activity containing a set of choices.
         When overridden in a derived class, appends choices to the activity when the user is prompted for input.
         Helper function to compose an output activity containing a set of choices.
 
-        :param prompt: The prompt to append the user's choice to.
+        :param prompt: The prompt to append the user's choice to
         :type prompt:  
-        :param channel_id: ID of the channel the prompt is being sent to.
+        :param channel_id: Id of the channel the prompt is being sent to
         :type channel_id: str
-        :param: choices: List of choices to append.
-        :type choices:  :class:List
-        :param: style: Configured style for the list of 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.
+        :param: choices: List of choices to append
+        :type choices:  :class:`List`
+        :param: style: Configured style for the list of 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
 
-        .. remarks::
+        .. note::
             If the task is successful, the result contains the updated activity.
         """
         # Get base prompt text (if any)