docs(menu): add docstrings to BaseMenu

.github/dependabot.yml

@@ -1,7 +1,7 @@
 version: 2
 updates:
   - package-ecosystem: "pip"
-    directory: "/" # Location of package manifests
+    directory: "/"
     schedule:
       interval: "daily"
     assignees:

CHANGELOG.md

@@ -14,6 +14,7 @@
 
 ### Documentation
 
+   - Add docstrings to `BaseMenu`
    - Add issue templates ([64c006258e373a97d0a9f83318af02c4310b585b](https://github.com/hearot/pyrubrum/commit/64c006258e373a97d0a9f83318af02c4310b585b))
    - Add the official pronunciation for Pyrubrum ([b6d1fe8e01f79007338cd4a6dfe409c406c12cba](https://github.com/hearot/pyrubrum/commit/b6d1fe8e01f79007338cd4a6dfe409c406c12cba))
    - Delete duplicate issue templates ([10cba65c31a5c3556b39cc328d097b62dfbd5e1b](https://github.com/hearot/pyrubrum/commit/10cba65c31a5c3556b39cc328d097b62dfbd5e1b))
@@ -24,7 +25,7 @@
    - Add space before reference links ([dfbf7a55f3a7de666703b1dced404d1ce7b0ee7a](https://github.com/hearot/pyrubrum/commit/dfbf7a55f3a7de666703b1dced404d1ce7b0ee7a))
    - Capitalize only the first character of a commit message ([2996f7c91723902b4e998fb94b6d31c60685d386](https://github.com/hearot/pyrubrum/commit/2996f7c91723902b4e998fb94b6d31c60685d386))
    - Do no more raise `TypeError` while formatting commits ([56f1e533c12bdf75e63714d125319bb72da7d916](https://github.com/hearot/pyrubrum/commit/56f1e533c12bdf75e63714d125319bb72da7d916))
-   - Fix `commit-message` for Dependabot
+   - Fix `commit-message` for Dependabot ([a13cfeae848d83339a902373ddcb0287fc306d87](https://github.com/hearot/pyrubrum/commit/a13cfeae848d83339a902373ddcb0287fc306d87))
    - Hide the sha-1 hash of the current commit ([ab6478e610ef828744d5c6e54a1d54fff92372e8](https://github.com/hearot/pyrubrum/commit/ab6478e610ef828744d5c6e54a1d54fff92372e8))
 
 ### New features

pyrubrum/base_menu.py

@@ -35,38 +35,110 @@
 
 @dataclass(eq=False, init=False, repr=True)
 class BaseMenu(ABC):
+    """Basic represention of a menu, which is an entity that has got by definition
+    a name and a unique identifier.
+
+    The purpose of this class is to give a general interface for a menu, as it
+    doesn't implement anything except for the generation of both buttons and
+    hashes.
+
+    A sample implementation of this interface is `Menu`.
+
+    Attributes:
+        name (str): The name you give to the menu, which will be used as the
+            text of callback button, if needed.
+        menu_id (str): The unique identifier given to the menu, which will
+            refer unequivocally to this entity. The hash for this class is
+            generated relying on the content of this field.
+
+    Note:
+        In order to create a subclass or to access this interface, you will
+        need to implement all the defined abstract methods, which are
+        `get_content`, `keyboard, `on_callback`, `on_message`. Otherwise, you
+        will get an error.
+
+    Warning:
+        Avoid using the same identifier for other entities, as it will result
+        in ambiguity.
+    """
+
     name: str
     menu_id: str
 
-    def __hash__(self):
+    def __hash__(self) -> int:
+        """The hash generator of a menu, relying on the unique identifier
+        (`menu_id`) which is assigned to it.
+
+        Returns:
+            int: The unique hash which is generated for this entity.
+        """
         return hash(self.menu_id)
 
     def __init__(self, name: str, menu_id: str):
+        """Initialize the class with a custom name and unique identifier.
+
+        Args:
+            name (str): The name you give to the menu, which will be used as
+                the text of callback button, if needed.
+            menu_id (str): The unique identifier given to the menu, which will
+                refer unequivocally to this entity. The hash for this class is
+                generated relying on the content of this field.
+        """
         self.name = name
         self.menu_id = menu_id
 
-    @abstractmethod
-    def get_content(self) -> Union[InputMedia, str]:
-        raise NotImplementedError
-
-    @abstractmethod
-    def on_callback(
+    def button(
         self,
         handler: BaseHandler,
         client: Client,
-        callback: CallbackQuery,
+        context: Union[CallbackQuery, Message],
         parameters: Dict[str, Any],
-    ):
-        raise NotImplementedError
+    ) -> Button:
+        """Create an inline button which refers to this menu, using `name` as
+        the content of the text field and `menu_id` as the unique identifier
+        of the `Button` object.
 
-    def button(
+        Args:
+            handler (BaseHandler): The handler which coordinates the management
+                of the menus.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context which the
+                button is generated for.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                the handler.
+
+        Returns:
+            Button: The generated button.
+        """
+        return Button(self.name, self.menu_id, parameters)
+
+    @abstractmethod
+    def get_content(
         self,
         handler: BaseHandler,
         client: Client,
         context: Union[CallbackQuery, Message],
         parameters: Dict[str, Any],
-    ) -> Button:
-        return Button(self.name, self.menu_id, parameters)
+    ) -> Union[InputMedia, str]:
+        """This abstract method is intended to be implemented as a generator
+        for the content of the menu (i.e. what the user will see after clicking
+        on the inline button or referencing to the menu using a bot command).
+
+        Args:
+            handler (BaseHandler): The handler which coordinates the management
+                of the menus.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context which the
+                button is generated for.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                the handler.
+
+        Returns:
+            Union[InputMedia, str]: The content of the menu, which is then
+                displayed to the user as a media (if it is a subclass of
+                `InputMedia`) or a message (if it is just a string).
+        """
+        raise NotImplementedError
 
     @abstractmethod
     def keyboard(
@@ -76,6 +148,44 @@ def keyboard(
         context: Union[CallbackQuery, Message],
         parameters: Dict[str, Any],
     ) -> InlineKeyboardMarkup:
+        """This abstract method is intended to be implemented as a generator
+        for the keyboard of the menu (aka the inline keyboard).
+
+        Args:
+            handler (BaseHandler): The handler which coordinates the management
+                of the menus.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context which the
+                button is generated for.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                the handler.
+
+        Returns:
+            InlineKeyboardMarkup: The generated inline keyboard, which is then
+                displayed to the user
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def on_callback(
+        self,
+        handler: BaseHandler,
+        client: Client,
+        callback: CallbackQuery,
+        parameters: Dict[str, Any],
+    ):
+        """This abstract method is intended to be implemented and is called
+        whenever a callback query is handled and refers to this menu.
+
+        Args:
+            handler (BaseHandler): The handler which coordinates the management
+                of the menus.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context which the
+                button is generated for.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                to the handler.
+        """
         raise NotImplementedError
 
     @abstractmethod
@@ -86,4 +196,16 @@ def on_message(
         message: Message,
         parameters: Dict[str, Any],
     ):
+        """This abstract method is intended to be implemented and is called
+        whenever a message is handled and refers to this menu.
+
+        Args:
+            handler (BaseHandler): The handler which coordinates the management
+                of the menus.
+            client (Client): The client which is linked to the handler.
+            context (Union[CallbackQuery, Message]): The context which the
+                button is generated for.
+            parameters (Dict[str, Any]): The parameters which were passed to
+                to the handler.
+        """
         raise NotImplementedError