Docs: Clean-up docstrings for wildcard query methods and classes intr…

…oduced in #62. (#63)

Co-authored-by: Kirk Rodrigues <[email protected]>

clp_ffi_py/ir/query_builder.py

@@ -9,9 +9,9 @@
 from clp_ffi_py.ir.native import Query
 from clp_ffi_py.wildcard_query import FullStringWildcardQuery, WildcardQuery
 
-_add_wildcard_query_deprecation_warning_message: str = "The wildcard query must be explicitly "
-"created and passed as a parameter to this function. QueryBuilder should only accept instances of "
-"`clp_ffi_py.wildcard_query.WildcardQuery`."
+_add_wildcard_query_deprecation_warning_message: str = "Instead, use :meth:`add_wildcard_query`"
+" with either a :class:`~clp_ffi_py.wildcard_query.FullStringWildcardQuery` or "
+" :class:`~clp_ffi_py.wildcard_query.SubstringWildcardQuery`."
 
 
 class QueryBuilderException(Exception):
@@ -115,9 +115,6 @@ class of :class:`~clp_ffi_py.wildcard_query.WildcardQuery`.
     def add_wildcard_query(
         self, wildcard_query: Union[str, WildcardQuery], case_sensitive: bool = False
     ) -> QueryBuilder:
-        """
-        This method is the implementation of `add_wildcard_query`.
-        """
         if isinstance(wildcard_query, WildcardQuery):
             self._wildcard_queries.append(wildcard_query)
             return self

clp_ffi_py/wildcard_query.py

@@ -5,31 +5,32 @@
 
 class WildcardQuery:
     """
-    This class defines an abstract wildcard query. It includes a wildcard string
-    and a boolean value to indicate if the match is case-sensitive.
+    An abstract class defining a wildcard query. Users should instantiate a
+    wildcard query through :class:`SubstringWildcardQuery` or
+    :class:`FullStringWildcardQuery`.
 
-    A wildcard string may contain the following types of supported wildcards:
+    A wildcard string may contain the following types of wildcards:
 
     1. '*': match 0 or more characters.
     2. '?': match any single character.
 
     Each wildcard can be escaped using a preceding '\\\\' (a single backslash).
-    Other characters which are escaped are treated as normal characters.
+    Other characters that are escaped are treated as normal characters.
     """
 
     @deprecated(
         version="0.0.12",
-        reason="`clp_ffi_py.wildcard_query.WildcardQuery` is supposed to be an abstract class and"
-        " should not be used directly. To create a wildcard query, please explicit instantiate"
-        " `clp_ffi_py.wildcard_query.SubstringWildcardQuery` or"
-        " `clp_ffi_py.wildcard_query.FullStringWildcardQuery`.",
+        reason=":class:`WildcardQuery` will soon be made abstract and should"
+        " not be used directly. To create a wildcard query, use"
+        " :class:`SubstringWildcardQuery` or :class:`FullStringWildcardQuery`"
+        " instead.",
     )
     def __init__(self, wildcard_query: str, case_sensitive: bool = False):
         """
         Initializes a wildcard query using the given parameters.
 
         :param wildcard_query: Wildcard query string.
-        :param case_sensitive: Case sensitive indicator.
+        :param case_sensitive: Whether to perform case-sensitive matching.
         """
         self._wildcard_query: str = wildcard_query
         self._case_sensitive: bool = case_sensitive
@@ -60,20 +61,20 @@ def case_sensitive(self) -> bool:
 
 class SubstringWildcardQuery(WildcardQuery):
     """
-    This class defines a substring wildcard query.
+    A wildcard query that can match a substring in a log event's message, in
+    contrast with :class:`FullStringWildcardQuery` where the query needs to
+    match the entire message.
 
-    It is derived from
-    :class:`~clp_ffi_py.WildcardQuery`, adding both a prefix and a postfix
-    wildcard ("*") to the input wildcard string. This allows the query to match
-    any substring within a log message.
+    This class is derived from :class:`WildcardQuery` by adding both a prefix
+    and a postfix wildcard ("*") to the input wildcard string.
     """
 
     def __init__(self, substring_wildcard_query: str, case_sensitive: bool = False):
         """
         Initializes a substring wildcard query using the given parameters.
 
         :param substring_wildcard_query: Wildcard query string.
-        :param case_sensitive: Case sensitive indicator.
+        :param case_sensitive: Whether to perform case-sensitive matching.
         """
         substring_wildcard_query = "*" + substring_wildcard_query + "*"
         with warnings.catch_warnings():
@@ -83,15 +84,24 @@ def __init__(self, substring_wildcard_query: str, case_sensitive: bool = False):
 
 class FullStringWildcardQuery(WildcardQuery):
     """
-    This class defines a full string wildcard query.
+    A wildcard query where the query must match the entirety of the log event's
+    message, in contrast with :class:`SubstringWildcardQuery` where the query
+    only needs to match a substring.
 
-    It is derived from
-    :class:`~clp_ffi_py.WildcardQuery`, and uses the input wildcard string
-    directly to create the query. This ensures that the query matches only the
-    entire log message.
+    This class is derived from :class:`WildcardQuery` as a more explicit
+    interface for full-string matches.
+
+    Users can create a match that's anchored to only one end of the message by
+    adding a prefix OR postfix wildcard ("*").
     """
 
     def __init__(self, full_string_wildcard_query: str, case_sensitive: bool = False):
+        """
+        Initializes a full-string wildcard query using the given parameters.
+
+        :param full_string_wildcard_query: Wildcard query string.
+        :param case_sensitive: Whether to perform case-sensitive matching.
+        """
         with warnings.catch_warnings():
             warnings.simplefilter("ignore", DeprecationWarning)
             super().__init__(full_string_wildcard_query, case_sensitive)

docs/src/api/clp_ffi_py.ir.query_builder.rst

@@ -2,6 +2,39 @@ clp\_ffi\_py.ir.query\_builder module
 =====================================
 
 .. automodule:: clp_ffi_py.ir.query_builder
-   :members:
-   :undoc-members:
-   :show-inheritance:
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: QueryBuilder
+
+    .. autoclass:: QueryBuilder
+        :members:
+        :undoc-members:
+        :show-inheritance:
+        :exclude-members: __init__, __new__, add_wildcard_query
+
+        .. method:: add_wildcard_query(wildcard_query: WildcardQuery) -> QueryBuilder
+
+            Adds the given wildcard query to the wildcard query list.
+
+            :param WildcardQuery wildcard_query: The wildcard query object to add.
+            :returns: self.
+            :rtype: QueryBuilder
+
+        .. method:: add_wildcard_query(wildcard_query: str, case_sensitive: bool = False) \
+            -> QueryBuilder
+            :no-index:
+
+            Constructs and adds a :class:`~clp_ffi_py.wildcard_query.WildcardQuery` to the wildcard
+            query list.
+
+            .. deprecated:: 0.0.12
+                Use :meth:`add_wildcard_query` with either a
+                :class:`~clp_ffi_py.wildcard_query.FullStringWildcardQuery` or
+                :class:`~clp_ffi_py.wildcard_query.SubstringWildcardQuery`
+                instead.
+
+            :param str wildcard_query: The wildcard query string to add.
+            :param bool case_sensitive: Whether to perform case-sensitive matching.
+            :returns: self.
+            :rtype: QueryBuilder