fix: resolve numpydoc docstring warnings

- Convert function summaries to infinitive verb form
- Fix parameter and return value descriptions
- Make docstrings more concise and accurate

Fixes scribe-org#547

src/scribe_data/check/check_query_forms.py

@@ -175,7 +175,7 @@ def extract_form_qids(form_text: str):
 
 def check_form_label(form_text: str):
     """
-    Checks that the label of the form matches the representation label.
+    Check that the label of the form matches the representation label.
 
     Parameters
     ----------
@@ -217,11 +217,11 @@ def check_form_label(form_text: str):
 
 def check_query_formatting(form_text: str):
     """
-    Checks the formatting of the given SPARQL query text for common formatting issues.
+    Check the formatting of the given SPARQL query text for common formatting issues.
 
     Parameters
     ----------
-    query_text : str
+    form_text : str
         The SPARQL query text to check.
 
     Returns
@@ -245,7 +245,7 @@ def check_query_formatting(form_text: str):
 
 def return_correct_form_label(qids: list):
     """
-    Returns the correct label for a lexeme form representation given the QIDs that compose it.
+    Return the correct label for a lexeme form representation given the QIDs that compose it.
 
     Parameters
     ----------
@@ -254,8 +254,8 @@ def return_correct_form_label(qids: list):
 
     Returns
     -------
-    correct_label : str
-        The label for the representation given the QIDs.
+    str
+        The label for the representation given the QIDs..
     """
     if not qids:
         return "Invalid query formatting found"
@@ -281,22 +281,17 @@ def return_correct_form_label(qids: list):
 
 def validate_forms(query_text: str) -> str:
     """
-    Validates the SPARQL query by checking:
-        1. Order of variables in SELECT and WHERE clauses
-        2. Presence and correct definition of forms
-        3. Form labels and representations
-        4. Query formatting
+    Validate SPARQL query by checking variable order in SELECT and WHERE clauses, Presence and correct definition of forms, Form labels and representations and Query formatting.
 
     Parameters
     ----------
-    query_file : str
+    query_text : str
         The SPARQL query text as a string.
 
     Returns
     -------
     str
-        Error message if there are any issues with the order of variables or forms,
-        otherwise an empty string.
+        Error message if there are any issues with the order of variables or forms, otherwise an empty string.
     """
     select_pattern = r"SELECT\s+(.*?)\s+WHERE"
 
@@ -377,7 +372,7 @@ def validate_forms(query_text: str) -> str:
 
 def check_docstring(query_text: str) -> bool:
     """
-    Checks the docstring of a SPARQL query text to ensure it follows the standard format.
+    Check the docstring of a SPARQL query text to ensure it follows the standard format.
 
     Parameters
     ----------
@@ -419,7 +414,7 @@ def check_docstring(query_text: str) -> bool:
 
 def check_forms_order(query_text):
     """
-    Parses and orders variable names from a SPARQL query text based on a lexeme_form_metadata.json.
+    Parse and order variable names from a SPARQL query text based on a lexeme_form_metadata.json.
 
     Parameters
     ----------
@@ -496,8 +491,7 @@ def compare_key(components):
 
 def check_optional_qid_order(query_file: str) -> str:
     """
-    Checks the order of QIDs in optional statements within a SPARQL query file to ensure they
-    align with the expected sequence based on label features.
+    Check the order of QIDs in optional statements within a SPARQL query file to ensure they align with the expected sequence based on label features.
 
     Parameters
     ----------
@@ -538,7 +532,7 @@ def check_optional_qid_order(query_file: str) -> str:
 
 def check_query_forms() -> None:
     """
-    Validates SPARQL queries in the language data directory to check for correct form QIDs and formatting.
+    Validate SPARQL queries in the language data directory to check for correct form QIDs and formatting.
     """
     error_output = ""
     index = 0

src/scribe_data/check/check_query_identifiers.py

@@ -37,7 +37,7 @@
 
 def is_valid_language(query_file: Path, lang_qid: str) -> bool:
     """
-    Validates the language QID against the expected QID for the directory.
+    Validate the language QID against the expected QID for the directory.
 
     Parameters
     ----------
@@ -75,7 +75,7 @@ def is_valid_language(query_file: Path, lang_qid: str) -> bool:
 
 def is_valid_data_type(query_file: Path, data_type_qid: str) -> bool:
     """
-    Validates the data type QID against the expected QID for the directory.
+    Validate the data type QID against the expected QID for the directory.
 
     Parameters
     ----------
@@ -103,7 +103,7 @@ def is_valid_data_type(query_file: Path, data_type_qid: str) -> bool:
 
 def extract_qid_from_sparql(file_path: Path, pattern: str) -> str:
     """
-    Extracts the QID from a SPARQL query file based on the provided pattern.
+    Extract the QID from a SPARQL query file based on the provided pattern.
 
     Parameters
     ----------
@@ -137,7 +137,7 @@ def extract_qid_from_sparql(file_path: Path, pattern: str) -> str:
 
 def check_query_identifiers() -> None:
     """
-    Validates SPARQL queries in the language data directory to check for correct language and data type QIDs.
+    Validate SPARQL queries in the language data directory to check for correct language and data type QIDs.
     """
     language_pattern = r"\?lexeme dct:language wd:Q\d+"
     data_type_pattern = r"wikibase:lexicalCategory\s+wd:Q\d+"

src/scribe_data/cli/cli_utils.py

@@ -30,7 +30,7 @@
 
 def correct_data_type(data_type: str) -> str:
     """
-    Corrects common versions of data type arguments so users can choose between them.
+    Correct common versions of data type arguments to their standardized form.
 
     Parameters
     ----------
@@ -39,7 +39,8 @@ def correct_data_type(data_type: str) -> str:
 
     Returns
     -------
-    The data_type value or a corrected version of it.
+    str
+        The data_type value or a corrected version of it.
     """
     all_data_types = data_type_metadata.keys()
 
@@ -56,7 +57,14 @@ def correct_data_type(data_type: str) -> str:
 
 def print_formatted_data(data: Union[dict, list], data_type: str) -> None:
     """
-    Prints a formatted output from the Scribe-Data CLI.
+    Print formatted output from the Scribe-Data CLI.
+
+    Parameters
+    ----------
+    data : Union[dict, list]
+        The data to format and print.
+    data_type : str
+        The type of data being printed, used to determine formatting style.
     """
     if not data:
         print(f"No data available for data type '{data_type}'.")
@@ -118,7 +126,7 @@ def validate_language_and_data_type(
     data_type: Union[str, List[str], bool, None],
 ):
     """
-    Validates that the language and data type QIDs are not None.
+    Validate that the language and data type QIDs are not None.
 
     Parameters
     ----------
@@ -128,6 +136,11 @@ def validate_language_and_data_type(
     data_type : str or list
         The data type(s) to validate.
 
+    Returns
+    -------
+    bool
+        True if validation passes, otherwise raises ValueError.
+
     Raises
     ------
     ValueError
@@ -136,16 +149,14 @@ def validate_language_and_data_type(
 
     def validate_single_item(item, valid_options, item_type):
         """
-        Validates a single item against a list of valid options, providing error messages and suggestions.
+        Validate a single item against a list of valid options, providing error messages and suggestions.
 
         Parameters
         ----------
         item : str
             The item to validate.
-
         valid_options : list
             A list of valid options against which the item will be validated.
-
         item_type : str
             A description of the item type (e.g., "language", "data-type") used in error messages.
 

src/scribe_data/cli/convert.py

@@ -53,28 +53,23 @@ def convert_to_json(
     ----------
     language : str
         The language of the file to convert.
-
     data_type : Union[str, List[str]]
         The data type of the file to convert.
-
     output_type : str
         The output format, should be "json".
-
     input_file : str
         The input CSV/TSV file path.
-
     output_dir : Path
         The output directory path for results.
-
     overwrite : bool
         Whether to overwrite existing files.
-
     identifier_case : str
         The case format for identifiers. Default is "camel".
 
     Returns
     -------
     None
+        A JSON file.
     """
     if not language:
         raise ValueError(f"Language '{language.capitalize()}' is not recognized.")
@@ -207,13 +202,10 @@ def convert_to_csv_or_tsv(
     ----------
     language : str
         The language of the file to convert.
-
     data_type : Union[str, List[str]]
         The data type of the file to convert.
-
     output_type : str
         The output format, should be "csv" or "tsv".
-
     input_file : str
         The input JSON file path.
 
@@ -229,6 +221,7 @@ def convert_to_csv_or_tsv(
     Returns
     -------
     None
+        A CSV/TSV files.
     """
     if not language:
         raise ValueError(f"Language '{language.capitalize()}' is not recognized.")
@@ -387,34 +380,29 @@ def convert_to_sqlite(
     identifier_case: str = "camel",
 ) -> None:
     """
-    Converts a Scribe-Data output file to an SQLite file.
+    Convert a Scribe-Data output file to SQLite format.
 
     Parameters
     ----------
     language : str
         The language of the file to convert.
-
     data_type : str
         The data type of the file to convert.
-
     output_type : str
         The output format, should be "sqlite".
-
-    input_file : Path
+    input_file : str, optional
         The input file path for the data to be converted.
-
-    output_dir : Path
+    output_dir : str, optional
         The output directory path for results.
-
-    overwrite : bool
+    overwrite : bool, optional
         Whether to overwrite existing files.
-
-    identifier_case : str
+    identifier_case : str, optional
         The case format for identifiers. Default is "camel".
 
     Returns
     -------
-    A SQLite file saved in the given location.
+    None
+        A SQLite file saved in the given location.
     """
     if input_file:
         input_file = Path(input_file)
@@ -461,33 +449,27 @@ def convert_wrapper(
 
     Parameters
     ----------
-    language : Union[str, List[str]]
+    languages : Union[str, List[str]]
         The language(s) of the data to convert.
-
-    data_type : Union[str, List[str]]
+    data_types : Union[str, List[str]]
         The data type(s) of the data to convert.
-
     output_type : str
-        The desired output format. It can be 'json', 'csv', 'tsv', or 'sqlite'.
-
-    input_file : Union[str, List[str]]
+        The desired output format. Can be 'json', 'csv', 'tsv', or 'sqlite'.
+    input_files : Union[str, List[str]]
         The path(s) to the input file(s).
-
-    output_dir : str, optional
-        The output directory where converted files will be stored. Defaults to None.
-
+    output_dir : str
+        The output directory where converted files will be stored.
     overwrite : bool, optional
-        Whether to overwrite existing output files. Defaults to False.
-
-    identifier_case : str
+        Whether to overwrite existing output files.
+    identifier_case : str, optional
         The case format for identifiers. Default is "camel".
-
-    all : bool
+    all : bool, optional
         Convert all languages and data types.
 
     Returns
     -------
     None
+        This function does not return any value; it performs a conversion operation.
     """
     output_type = output_type.lower()