Rewrite storage and visitor module docs

Remove typing from method docs, change some wording, and spell out 'Arguments` instead
of 'Args'

Refs #10

alchemical_storage/storage/storage.py

@@ -1,4 +1,4 @@
-"""Module defining storage services."""
+"""Module containing the storage protocol and a database storage implementation."""
 
 import abc
 import functools
@@ -24,94 +24,100 @@ class StorageABC(abc.ABC, Generic[AlchemyModel]):
     def get(self, identity: Any) -> AlchemyModel:
         """Get a resource from storage.
 
-        Args:
-            identity (Any): The description
+        Arguments:
+            identity: The description
 
         Returns:
-            AlchemyModel: Object that can be serialized to output for api
+            A model that can be serialized to output for api
 
         """
 
     @abc.abstractmethod
     def index(self, **kwargs) -> list[AlchemyModel]:
-        """Get a list resources from storage.
+        """Get a list of resources from storage.
+
+        Arguments:
+            **kwargs: Parameters to pass to the statement visitors.
 
         Returns:
-            list[AlchemyModel]: List of objects that can be serialized to output for api
+            A list of models that can be serialized to output for api.
 
         """
 
     @abc.abstractmethod
     def count(self, **kwargs) -> int:
         """Count resources in storage.
 
+        Arguments:
+            **kwargs: Parameters to pass to the statement visitors.
+
         Returns:
-            int: Count of objects
+            The count of resources in storage.
 
         """
 
     @abc.abstractmethod
     def put(self, identity: Any, data: dict[str, Any]) -> AlchemyModel:
         """Put a new resource to storage.
 
-        Args:
-            identity (Any): The resource identifier
-            data (dict[str, Any]): Data that can be deserialized to Any for create
+        Arguments:
+            identity: The resource identifier
+            data: Data that can be deserialized to create a new resource
 
         Returns:
-            AlchemyModel: Object that can be serialized to output for api
+            A model that can be serialized to output for api
 
         """
 
     @abc.abstractmethod
     def patch(self, identity: Any, data: dict[str, Any]) -> AlchemyModel:
         """Update a resource in storage.
 
-        Args:
-            identity (Any): The resource identifier
-            data (dict[str, Any]): Data that can be deserialized to Any for update
+        Arguments:
+            identity: The resource identifier
+            data: Data that can be deserialized to update the resource
 
         Returns:
-            AlchemyModel: Object that can be serialized to output for api
+            A model that can be serialized to output for api
 
         """
 
     @abc.abstractmethod
     def delete(self, identity: Any) -> AlchemyModel:
         """Delete a resource from storage.
 
-        Args:
-            identity (Any): The resource identifier
+        Arguments:
+            identity: The resource identifier
 
         Returns:
-            AlchemyModel: Object that can be serialized to output for api
+            A model that can be serialized to output for api
 
         """
 
     @abc.abstractmethod
     def __contains__(self, identity: Any) -> bool:
-        """Checks if resource identified by identity eAny.
+        """Checks if resource identified by ``identity`` exists in storage.
 
-        Args:
-            identity (Any): The resource identifier
+        Arguments:
+            identity: The resource identifier
 
         Returns:
-            bool: Whether the resource exists
+            Whether the resource exists in storage
 
         """
 
 
 class DatabaseStorage(StorageABC, DatabaseIndex, Generic[AlchemyModel]):
     """SQLAlchemy model storage in sql database.
 
-    Args:
-        session (Session): The SQLAlchemy session to use for database operations
-        entity (Type[AlchemyModel]): The SQLAlchemy model to use for database operations
-        storage_schema (SQLAlchemySchema): The marshmallow schema to use for
+    Arguments:
+        session: The SQLAlchemy session to use for database operations
+        entity: The SQLAlchemy model to use for database operations
+        storage_schema: The marshmallow schema to use for
             serialization
-        primary_key (str|Sequence[str]): The primary key of the entity (Optional,
+        primary_key: The primary key of the entity (Optional,
             defaults to "slug")
-        statement_visitors (Optional[list[StatementVisitor]]): List of statement
+        statement_visitors: List of statement
             visitors to apply to all statements
 
     """

alchemical_storage/visitor.py

@@ -16,8 +16,8 @@ def visit_statement(self, statement: T, params: dict[str, Any]) -> T:
         """Visit a statement.
 
         Args:
-            statement (T): The statement to visit
-            params (dict[str, Any]): The parameters passed by the
+            statement: The statement to visit
+            params: The parameters passed by the
                 :class:`alchemical_storage.storage.DatabaseStorage` when this method is
                 called