Yet another round of doc fixes (#155)

* Refactor docstrings in InputFile and InputFileDownloader classes for clarity and consistency

* Update type hints in docstrings for TurnContext and ClaimsIdentity for clarity

* Update type hints in AgentState and BotStatePropertyAccessor docstrings for clarity

* Clarify class reference in AgentState constructor docstring

Author: cleemullins

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/input_file.py

@@ -16,10 +16,12 @@
 class InputFile:
     """A file sent by the user to the bot.
 
-    Attributes:
-        content (bytes): The downloaded content of the file.
-        content_type (str): The content type of the file.
-        content_url (Optional[str]): Optional. URL to the content of the file.
+    :param content: The downloaded content of the file.
+    :type content: bytes
+    :param content_type: The content type of the file.
+    :type content_type: str
+    :param content_url: Optional. URL to the content of the file.
+    :type content_url: Optional[str]
     """
 
     content: bytes
@@ -29,17 +31,19 @@ class InputFile:
 
 class InputFileDownloader(ABC):
     """
-    A plugin responsible for downloading files relative to the current user's input.
+    Abstract base class for a plugin responsible for downloading files provided by the user.
+
+    Implementations should download any files referenced by the incoming activity and return a
+    list of :class:`InputFile` instances representing the downloaded content.
     """
 
     @abstractmethod
     async def download_files(self, context: TurnContext) -> List[InputFile]:
         """
-        Download any files relative to the current user's input.
-
-        Args:
-            context (TurnContext): Context for the current turn of conversation.
+        Download any files referenced by the incoming activity for the current turn.
 
-        Returns:
-            List[InputFile]: A list of input files.
+        :param context: The turn context for the current request.
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
+        :return: A list of downloaded :class:`InputFile` objects.
+        :rtype: list[:class:`microsoft_agents.hosting.core.app.input_file.InputFile`]
         """

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/channel_adapter.py

@@ -40,7 +40,7 @@ async def send_activities(
         Sends a set of activities to the user. An array of responses from the server will be returned.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activities: The activities to send.
         :type activities: list[Activity]
         :return:
@@ -53,7 +53,7 @@ async def update_activity(self, context: TurnContext, activity: Activity):
         Replaces an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param activity: New replacement activity.
         :type activity: :class:`microsoft_agents.activity.Activity`
         :return:
@@ -68,7 +68,7 @@ async def delete_activity(
         Deletes an existing activity.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param reference: Conversation reference for the activity to delete.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :return:
@@ -102,7 +102,7 @@ async def continue_conversation(
         :param reference: A reference to the conversation to continue.
         :type reference: :class:`microsoft_agents.activity.ConversationReference`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
         :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
         :param audience:A value signifying the recipient of the proactive message.
@@ -124,11 +124,11 @@ async def continue_conversation_with_claims(
         to the user.
 
         :param claims_identity: A :class:`microsoft_agents.hosting.core.ClaimsIdentity` for the conversation.
-        :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
+        :type claims_identity: :class:`microsoft_agents.hosting.core.authorization.ClaimsIdentity`
         :param continuation_activity: The activity to send.
         :type continuation_activity: :class:`microsoft_agents.activity.Activity`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         """
@@ -155,9 +155,9 @@ async def create_conversation(
         :param audience: A value signifying the recipient of the proactive message.
         :type audience: str
         :param conversation_parameters: The information to use to create the conversation
-        :type conversation_parameters: :class:`microsoft_agents.activity.models.ConversationParameters`
+        :type conversation_parameters: :class:`microsoft_agents.activity.ConversationParameters`
         :param callback: The method to call for the resulting agent turn.
-        :type callback: Callable[[TurnContext], Awaitable]
+        :type callback: Callable[[microsoft_agents.hosting.core.turn_context.TurnContext], Awaitable]
 
         :raises: Exception - Not implemented or when the implementation fails.
 
@@ -222,7 +222,7 @@ async def run_pipeline(
         the end of the chain.
 
         :param context: The context object for the turn.
-        :type context: :class:`TurnContext`
+        :type context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param callback: A callback method to run at the end of the pipeline.
         :type callback: Callable[[TurnContext], Awaitable]
         :return:

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/state/agent_state.py

@@ -68,11 +68,11 @@ class AgentState:
 
     def __init__(self, storage: Storage, context_service_key: str):
         """
-        Initializes a new instance of the :class:`AgentState` class.
+        Initializes a new instance of the :class:`microsoft_agents.hosting.core.state.agent_state.AgentState` class.
 
         :param storage: The storage layer this state management object will use to store and retrieve state
         :type storage:  :class:`microsoft_agents.hosting.core.storage.Storage`
-        :param context_service_key: The key for the state cache for this :class:`AgentState`
+        :param context_service_key: The key for the state cache for this :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`
         :type context_service_key: str
 
         .. remarks::
@@ -93,19 +93,19 @@ def get_cached_state(self, turn_context: TurnContext) -> CachedAgentState:
         from the turn context.
 
         :param turn_context: The context object for this turn.
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :return: The cached agent state instance.
         """
         return turn_context.turn_state.get(self._context_service_key)
 
     def create_property(self, name: str) -> StatePropertyAccessor:
         """
-        Creates a property definition and registers it with this :class:`AgentState`.
+        Creates a property definition and registers it with this :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`.
 
         :param name: The name of the property
         :type name: str
         :return: If successful, the state property accessor created
-        :rtype: :class:`StatePropertyAccessor`
+        :rtype: :class:`microsoft_agents.hosting.core.state.state_property_accessor.StatePropertyAccessor`
         """
         if not name or not name.strip():
             raise ValueError(
@@ -123,7 +123,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:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param force: Optional, true to bypass the cache
         :type force: bool
         """
@@ -141,7 +141,7 @@ async def save(self, turn_context: TurnContext, force: bool = False) -> None:
         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:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param force: Optional, true to save state to storage whether or not there are changes
         :type force: bool
         """
@@ -157,7 +157,7 @@ def clear(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:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :return: None
 
@@ -174,7 +174,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:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :return: None
         """
@@ -200,7 +200,7 @@ def get_value(
         Gets the value of the specified property in the turn context.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param property_name: The property name
         :type property_name: str
 
@@ -235,8 +235,6 @@ def delete_value(self, property_name: str) -> None:
         """
         Deletes a property from the state cache in the turn context.
 
-        :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
         :param property_name: The name of the property to delete
         :type property_name: str
 
@@ -254,8 +252,6 @@ def set_value(self, property_name: str, value: StoreItem) -> None:
         """
         Sets a property to the specified value in the turn context.
 
-        :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
         :param property_name: The property name
         :type property_name: str
         :param value: The value to assign to the property
@@ -272,15 +268,15 @@ def set_value(self, property_name: str, value: StoreItem) -> None:
 
 class BotStatePropertyAccessor(StatePropertyAccessor):
     """
-    Defines methods for accessing a state property created in a :class:`AgentState` object.
+    Defines methods for accessing a state property created in a :class:`microsoft_agents.hosting.core.state.agent_state.AgentState` object.
     """
 
     def __init__(self, agent_state: AgentState, name: str):
         """
-        Initializes a new instance of the :class:`BotStatePropertyAccessor` class.
+        Initializes a new instance of the :class:`microsoft_agents.hosting.core.state.agent_state.BotStatePropertyAccessor` class.
 
         :param agent_state: The state object to access
-        :type agent_state:  :class:`AgentState`
+        :type agent_state:  :class:`microsoft_agents.hosting.core.state.agent_state.AgentState`
         :param name: The name of the state property to access
         :type name: str
 
@@ -304,7 +300,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:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         """
         await self._agent_state.load(turn_context, False)
         self._agent_state.delete_value(self._name)
@@ -320,7 +316,7 @@ async def get(
         Gets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
         :param default_value_or_factory: Defines the default value for the property
         """
         await self._agent_state.load(turn_context, False)
@@ -355,7 +351,7 @@ async def set(self, turn_context: TurnContext, value: StoreItem) -> None:
         Sets the property value.
 
         :param turn_context: The context object for this turn
-        :type turn_context: :class:`TurnContext`
+        :type turn_context: :class:`microsoft_agents.hosting.core.turn_context.TurnContext`
 
         :param value: The value to assign to the property
         """