Reference comment fixes

libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_adapter.py

@@ -24,8 +24,7 @@
 
 class SlackAdapter(BotAdapter, ABC):
     """
-    BotAdapter that can handle incoming slack events.  Incoming slack events are deserialized to an Activity
-    that is dispatch through the middleware and bot pipeline.
+    BotAdapter that can handle incoming Slack events. Incoming Slack events are deserialized to an Activity that is dispatched through the middleware and bot pipeline.
     """
 
     def __init__(
@@ -41,11 +40,14 @@ async def send_activities(
         self, context: TurnContext, activities: List[Activity]
     ) -> List[ResourceResponse]:
         """
-        Standard BotBuilder adapter method to send a message from the bot to the messaging API.
+        Send a message from the bot to the messaging API.
 
         :param context: A TurnContext representing the current incoming message and environment.
+        :type context: :class:`botbuilder.core.TurnContext`
         :param activities: An array of outgoing activities to be sent back to the messaging API.
+        :type activities: :class:`typing.List[Activity]`
         :return: An array of ResourceResponse objects containing the IDs that Slack assigned to the sent messages.
+        :rtype: :class:`typing.List[ResourceResponse]`
         """
 
         if not context:
@@ -76,11 +78,14 @@ async def send_activities(
 
     async def update_activity(self, context: TurnContext, activity: Activity):
         """
-        Standard BotBuilder adapter method to update a previous message with new content.
+        Update a previous message with new content.
 
         :param context: A TurnContext representing the current incoming message and environment.
+        :type context: :class:`botbuilder.core.TurnContext`
         :param activity: The updated activity in the form '{id: `id of activity to update`, ...}'.
-        :return: A resource response with the Id of the updated activity.
+        :type activity: :class:`botbuilder.schema.Activity`
+        :return: A resource response with the ID of the updated activity.
+        :rtype: :class:`botbuilder.schema.ResourceResponse`
         """
 
         if not context:
@@ -106,11 +111,12 @@ async def delete_activity(
         self, context: TurnContext, reference: ConversationReference
     ):
         """
-        Standard BotBuilder adapter method to delete a previous message.
+        Delete a previous message.
 
         :param context: A TurnContext representing the current incoming message and environment.
-        :param reference: An object in the form "{activityId: `id of message to delete`,
-        conversation: { id: `id of slack channel`}}".
+        :type context: :class:`botbuilder.core.TurnContext`
+        :param reference: An object in the form "{activityId: `id of message to delete`,conversation: { id: `id of Slack channel`}}".
+        :type reference: :class:`botbuilder.schema.ConversationReference`
         """
 
         if not context:
@@ -135,15 +141,22 @@ async def continue_conversation(
         audience: str = None,
     ):
         """
-        Sends a proactive message to a conversation. Call this method to proactively send a message to a conversation.
-        Most _channels require a user to initiate a conversation with a bot before the bot can send activities
-        to the user.
+        Send a proactive message to a conversation.
+
+        .. remarks::
+
+            Most channels require a user to initiate a conversation with a bot before the bot can send activities to the user.
 
-        :param bot_id: Unused for this override.
         :param reference: A reference to the conversation to continue.
+        :type reference: :class:`botbuilder.schema.ConversationReference`
         :param callback: The method to call for the resulting bot turn.
+        :type callback: :class:`typing.Callable`
+        :param bot_id: Unused for this override.
+        :type bot_id: str
         :param claims_identity: A ClaimsIdentity for the conversation.
+        :type claims_identity: :class:`botframework.connector.auth.ClaimsIdentity`
         :param audience: Unused for this override.
+        :type audience: str
         """
 
         if not reference:
@@ -171,10 +184,14 @@ async def process(self, req: Request, logic: Callable) -> Response:
         """
         Accept an incoming webhook request and convert it into a TurnContext which can be processed by the bot's logic.
 
-        :param req: The aoihttp Request object
+        :param req: The aiohttp Request object.
+        :type req: :class:`aiohttp.web_request.Request`
         :param logic: The method to call for the resulting bot turn.
-        :return: The aoihttp Response
+        :type logic: :class:`tying.Callable`
+        :return: The aiohttp Response. 
+        :rtype: :class:`aiohttp.web_response.Response`
         """
+
         if not req:
             raise Exception("Request is required")
 

libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_helper.py

@@ -27,10 +27,12 @@ class SlackHelper:
     @staticmethod
     def activity_to_slack(activity: Activity) -> SlackMessage:
         """
-        Formats a BotBuilder activity into an outgoing Slack message.
+        Formats a BotBuilder Activity into an outgoing Slack message.
+
         :param activity: A BotBuilder Activity object.
-        :return: A Slack message object with {text, attachments, channel, thread ts} as well
-        as any fields found in activity.channelData
+        :type activity: :class:`botbuilder.schema.Activity`
+        :return: A Slack message object with {text, attachments, channel, thread ts} and any fields found in activity.channelData.
+        :rtype: :class:`SlackMessage`
         """
 
         if not activity:
@@ -83,13 +85,18 @@ def response(  # pylint: disable=unused-argument
         req: Request, code: int, text: str = None, encoding: str = None
     ) -> Response:
         """
-        Formats an aiohttp Response
-
-        :param req: The original aoihttp Request
-        :param code: The HTTP result code to return
-        :param text: The text to return
-        :param encoding: The text encoding.  Defaults to utf-8
+        Formats an aiohttp Response.
+
+        :param req: The original aiohttp Request.
+        :type req: :class:`aiohttp.web_request.Request`
+        :param code: The HTTP result code to return.
+        :type code: int
+        :param text: The text to return.
+        :type text: str
+        :param encoding: The text encoding. Defaults to UTF-8.
+        :type encoding: str
         :return: The aoihttp Response
+        :rtype: :class:`aiohttp.web_response.Response`
         """
 
         response = Response(status=code)
@@ -103,10 +110,12 @@ def response(  # pylint: disable=unused-argument
     @staticmethod
     def payload_to_activity(payload: SlackPayload) -> Activity:
         """
-        Creates an activity based on the slack event payload.
+        Creates an activity based on the Slack event payload.
 
-        :param payload: The payload of the slack event.
+        :param payload: The payload of the Slack event.
+        :type payload: :class:`SlackPayload`
         :return: An activity containing the event data.
+        :rtype: :class:`botbuilder.schema.Activity`
         """
 
         if not payload:
@@ -138,11 +147,14 @@ def payload_to_activity(payload: SlackPayload) -> Activity:
     @staticmethod
     async def event_to_activity(event: SlackEvent, client: SlackClient) -> Activity:
         """
-        Creates an activity based on the slack event data.
+        Creates an activity based on the Slack event data.
 
-        :param event: The data of the slack event.
+        :param event: The data of the Slack event.
+        :type event: :class:`SlackEvent`
         :param client: The Slack client.
+        :type client: :class:`SlackClient`
         :return: An activity containing the event data.
+        :rtype: :class:`botbuilder.schema.Activity`
         """
 
         if not event:
@@ -191,11 +203,14 @@ async def command_to_activity(
         body: SlackRequestBody, client: SlackClient
     ) -> Activity:
         """
-        Creates an activity based on a slack event related to a slash command.
+        Creates an activity based on a Slack event related to a slash command.
 
-        :param body: The data of the slack event.
+        :param body: The data of the Slack event.
+        :type body: :class:`SlackRequestBody`
         :param client: The Slack client.
+        :type client: :class:`SlackClient`
         :return: An activity containing the event data.
+        :rtype: :class:`botbuilder.schema.Activity`
         """
 
         if not body:
@@ -223,7 +238,9 @@ def query_string_to_dictionary(query: str) -> {}:
         Converts a query string to a dictionary with key-value pairs.
 
         :param query: The query string to convert.
+        :type query: str
         :return: A dictionary with the query values.
+        :rtype: :class:`typing.Dict`
         """
 
         values = {}
@@ -247,9 +264,12 @@ def deserialize_body(content_type: str, request_body: str) -> SlackRequestBody:
         """
         Deserializes the request's body as a SlackRequestBody object.
 
-        :param content_type: The content type of the body
-        :param request_body: The body of the request
-        :return: A SlackRequestBody object
+        :param content_type: The content type of the body.
+        :type content_type: str
+        :param request_body: The body of the request.
+        :type request_body: str
+        :return: A SlackRequestBody object.
+        :rtype: :class:`SlackRequestBody`
         """
 
         if not request_body:

libraries/botbuilder-adapters-slack/botbuilder/adapters/slack/slack_options.py

@@ -4,7 +4,7 @@
 
 class SlackAdapterOptions:
     """
-    Class for defining implementation of the SlackAdapter Options.
+    Defines the implementation of the SlackAdapter options.
     """
 
     def __init__(
@@ -14,10 +14,14 @@ def __init__(
         slack_client_signing_secret: str,
     ):
         """
-        Initializes new instance of SlackAdapterOptions
+        Initializes a new instance of SlackAdapterOptions.
+
         :param slack_verification_token: A token for validating the origin of incoming webhooks.
+        :type slack_verification_token: str
         :param slack_bot_token: A token for a bot to work on a single workspace.
-        :param slack_client_signing_secret: The token used to validate that incoming webhooks are originated from Slack.
+        :type slack_bot_token: str
+        :param slack_client_signing_secret: The token used to validate that incoming webhooks originated from Slack.
+        :type slack_client_signing_secret: str
         """
         self.slack_verification_token = slack_verification_token
         self.slack_bot_token = slack_bot_token
@@ -29,18 +33,20 @@ def __init__(
 
     async def get_token_for_team(self, team_id: str) -> str:
         """
-        A method that receives a Slack team id and returns the bot token associated with that team. Required for
-        multi-team apps.
-        :param team_id:Team ID.
-        :return:The bot token associated with the team.
+        Receives a Slack team ID and returns the bot token associated with that team. Required for multi-team apps.
+
+        :param team_id: The team ID.
+        :type team_id: str
+        :raises: :func:`NotImplementedError`
         """
         raise NotImplementedError()
 
     async def get_bot_user_by_team(self, team_id: str) -> str:
         """
-        A method that receives a Slack team id and returns the bot user id associated with that team. Required for
-        multi-team apps.
-        :param team_id:Team ID.
-        :return:The bot user id associated with that team.
+        A method that receives a Slack team ID and returns the bot user ID associated with that team. Required for multi-team apps.
+
+        :param team_id: The team ID.
+        :type team_id: str
+        :raises: :func:`NotImplementedError`
         """
         raise NotImplementedError()

libraries/botbuilder-ai/botbuilder/ai/luis/luis_recognizer.py

@@ -20,7 +20,7 @@
 
 class LuisRecognizer(Recognizer):
     """
-    A LUIS based implementation of <see cref="IRecognizer"/>.
+    A LUIS based implementation of :class:`botbuilder.core.Recognizer`.
     """
 
     # The value type for a LUIS trace activity.
@@ -45,7 +45,7 @@ def __init__(
         :type prediction_options: :class:`LuisPredictionOptions`, optional
         :param include_api_results: True to include raw LUIS API response, defaults to False.
         :type include_api_results: bool, optional
-        :raises TypeError:
+        :raises: TypeError
         """
 
         if isinstance(application, LuisApplication):
@@ -79,10 +79,9 @@ def top_intent(
         :type results: :class:`botbuilder.core.RecognizerResult`
         :param default_intent: Intent name to return should a top intent be found, defaults to None.
         :type default_intent: str, optional
-        :param min_score: Minimum score needed for an intent to be considered as a top intent. If all intents in
-        the set are below this threshold then the `defaultIntent` will be returned, defaults to 0.0.
+        :param min_score: Minimum score needed for an intent to be considered as a top intent. If all intents in the set are below this threshold then the `defaultIntent` is returned, defaults to 0.0.
         :type min_score: float, optional
-        :raises TypeError:
+        :raises: TypeError
         :return: The top scoring intent name.
         :rtype: str
         """
@@ -108,9 +107,9 @@ async def recognize(  # pylint: disable=arguments-differ
         telemetry_metrics: Dict[str, float] = None,
         luis_prediction_options: LuisPredictionOptions = None,
     ) -> RecognizerResult:
-        """Return results of the analysis (Suggested actions and intents).
+        """Return results of the analysis (suggested actions and intents).
 
-        :param turn_context: Context object containing information for a single turn of conversation with a user.
+        :param turn_context: Context object containing information for a single conversation turn with a user.
         :type turn_context: :class:`botbuilder.core.TurnContext`
         :param telemetry_properties: Additional properties to be logged to telemetry with the LuisResult event, defaults
          to None.
@@ -138,7 +137,7 @@ def on_recognizer_result(
     ):
         """Invoked prior to a LuisResult being logged.
 
-        :param recognizer_result: The Luis Results for the call.
+        :param recognizer_result: The LuisResult for the call.
         :type recognizer_result: :class:`botbuilder.core.RecognizerResult`
         :param turn_context: Context object containing information for a single turn of conversation with a user.
         :type turn_context: :class:`botbuilder.core.TurnContext`
@@ -187,11 +186,9 @@ def fill_luis_event_properties(
         :type recognizer_result: :class:`botbuilder.core.RecognizerResult`
         :param turn_context: Context object containing information for a single turn of conversation with a user.
         :type turn_context: :class:`botbuilder.core.TurnContext`
-        :param telemetry_properties: Additional properties to be logged to telemetry with the LuisResult event,
-         defaults to None
-        :param telemetry_properties: :class:`typing.Dict[str, str]`, optional
-        :return: A dictionary that is sent as "Properties" to :func:`botbuilder.core.BotTelemetryClient.track_event`
-        method for the BotMessageSend event.
+        :param telemetry_properties: Additional properties to be logged to telemetry with the LuisResult event, defaults to None.
+        :type telemetry_properties: :class:`typing.Dict[str, str]`, optional
+        :return: A dictionary sent as "Properties" to :func:`botbuilder.core.BotTelemetryClient.track_event` for the BotMessageSend event.
         :rtype: `typing.Dict[str, str]`
         """
 

libraries/botbuilder-ai/botbuilder/ai/qna/qnamaker.py

@@ -126,6 +126,7 @@ def get_low_score_variation(self, query_result: QueryResult) -> List[QueryResult
         :param query_result: User query output.
         :type query_result: :class:`QueryResult`
         :return: Filtered array of ambiguous questions.
+        :rtype: :class:`typing.List[QueryResult]`
         """
         return ActiveLearningUtils.get_low_score_variation(query_result)
 
@@ -166,14 +167,16 @@ async def fill_qna_event(
         """
         Fills the event properties and metrics for the QnaMessage event for telemetry.
 
-        :return: A tuple of event data properties and metrics that will be sent to the
-        :func:`botbuilder.core.BotTelemetryClient.track_event` method for the QnAMessage event.
-        The properties and metrics returned the standard properties logged
-        with any properties passed from the :func:`get_answers` method.
+        :param query_results: QnA service results.
+        :type quert_results: :class:`QueryResult`
+        :param turn_context: Context object containing information for a single turn of conversation with a user.
+        :type turn_context: :class:`botbuilder.core.TurnContext`
+        :param telemetry_properties: Properties to add/override for the event.
+        :type telemetry_properties: :class:`typing.Dict[str, str]`
+        :param telemetry_metrics: Metrics to add/override for the event.
+        :type telemetry_metrics: :class:`typing.Dict[str, float]`
         :return: Event properties and metrics for the QnaMessage event for telemetry.
         :rtype: :class:`EventData`
-        ------
-        EventData
         """
 
         properties: Dict[str, str] = dict()