Update various docstrings.

Author: KelSolaar

colour_datasets/__init__.py

@@ -8,11 +8,15 @@
 `Zenodo <https://zenodo.org>`__ under the `Colour Science - Datasets \
 <https://zenodo.org/communities/colour-science-datasets>`__ community.
 
+This package provides access to standardised colour science datasets including
+spectral power distributions, colour matching functions, and experimental data
+from research publications.
+
 Subpackages
 -----------
--   loaders: Dataset loaders.
--   records: *Zenodo* records management.
--   utilities:  Various utilities.
+-   loaders: Dataset loading and parsing utilities.
+-   records: *Zenodo* records management and configuration.
+-   utilities: Common utilities for dataset processing.
 """
 
 # isort: skip_file

colour_datasets/loaders/__init__.py

@@ -1,3 +1,14 @@
+"""
+Loaders
+=======
+
+Dataset loading and parsing utilities.
+
+This subpackage provides dataset loaders for various colour science datasets
+hosted on Zenodo, including spectral power distributions, colour matching
+functions, and experimental data from research publications.
+"""
+
 # isort: skip_file
 
 from __future__ import annotations
@@ -143,7 +154,7 @@
 
 def load(dataset: int | str) -> Any:
     """
-    Load given dataset: The dataset is pulled locally, i.e., synced if required
+    Load specified dataset: The dataset is pulled locally, i.e., synced if required
     and then its data is loaded.
 
     Parameters

colour_datasets/records/__init__.py

@@ -1,3 +1,14 @@
+"""
+Records
+=======
+
+Zenodo records management and configuration.
+
+This subpackage provides interfaces for managing Zenodo community records,
+configuration handling, and dataset metadata retrieval from the Colour Science
+Datasets community on Zenodo.
+"""
+
 # isort: skip_file
 
 from __future__ import annotations

colour_datasets/utilities/__init__.py

@@ -1,3 +1,13 @@
+"""
+Utilities
+=========
+
+Common utilities for dataset processing and manipulation.
+
+This subpackage provides file handling utilities, data compression tools,
+and spreadsheet processing functions to support dataset operations.
+"""
+
 # isort: skip_file
 
 from .common import (

colour_datasets/utilities/common.py

@@ -2,7 +2,7 @@
 Common Utilities
 ================
 
-Define the common utilities objects that don't fall in any specific category.
+Define common utility objects for file operations and data processing.
 """
 
 from __future__ import annotations
@@ -103,7 +103,7 @@ def update_to(
 
 def hash_md5(filename: str, chunk_size: int = 2**16) -> str:
     """
-    Compute the *Message Digest 5 (MD5)* hash of given file.
+    Compute the *Message Digest 5 (MD5)* hash of specified file.
 
     Parameters
     ----------
@@ -115,7 +115,7 @@ def hash_md5(filename: str, chunk_size: int = 2**16) -> str:
     Returns
     -------
     :class:`str`
-        *MD5* hash of given file.
+        *MD5* hash of specified file.
     """
 
     md5 = hashlib.md5()  # noqa: S324
@@ -135,7 +135,7 @@ def url_download(
     url: str, filename: str, md5: str | None = None, retries: int = 3
 ) -> None:
     """
-    Download given url and saves its content at given file.
+    Download specified url and saves its content at specified file.
 
     Parameters
     ----------
@@ -144,8 +144,8 @@ def url_download(
     filename
         File to save the url content at.
     md5
-        *Message Digest 5 (MD5)* hash of the content at given url. If provided
-        the saved content at given file will be hashed and compared to ``md5``.
+        *Message Digest 5 (MD5)* hash of the content at specified url. If provided
+        the saved content at specified file will be hashed and compared to ``md5``.
     retries
         Number of retries in case where a networking error occurs or the *MD5*
         hash is not matching.
@@ -200,7 +200,7 @@ def url_download(
 @cached(cache=TTLCache(maxsize=256, ttl=300))
 def json_open(url: str, retries: int = 3) -> Dict:
     """
-    Open given url and return its content as *JSON*.
+    Open specified url and return its content as *JSON*.
 
     Parameters
     ----------
@@ -256,7 +256,7 @@ def unpack_gzipfile(
     *args: Any,  # noqa: ARG001
 ) -> bool:
     """
-    Unpack given *GZIP* file to given extraction directory.
+    Unpack specified *GZIP* file to specified extraction directory.
 
     Parameters
     ----------

colour_datasets/utilities/spreadsheet.py

@@ -48,7 +48,7 @@
 
 def _column_number_to_letters(number: int) -> str:
     """
-    Convert given column number into a column letters.
+    Convert specified column number into a column letters.
 
     Right shifts the column index by 26 to find column letters in reverse
     order. These numbers are 1-based, and can be converted to ASCII
@@ -104,7 +104,7 @@ def _column_number_to_letters(number: int) -> str:
 
 def row_to_index(row: int | str) -> int:
     """
-    Return the 0-based index of given row name.
+    Return the 0-based index of specified row name.
 
     Parameters
     ----------
@@ -131,7 +131,7 @@ def row_to_index(row: int | str) -> int:
 
 def index_to_row(index: int) -> str:
     """
-    Return the row name of given 0-based index.
+    Return the row name of specified 0-based index.
 
     Parameters
     ----------
@@ -154,7 +154,7 @@ def index_to_row(index: int) -> str:
 
 def column_to_index(column: str) -> int:
     """
-    Return the 0-based index of given column letters.
+    Return the 0-based index of specified column letters.
 
     Parameters
     ----------
@@ -177,7 +177,7 @@ def column_to_index(column: str) -> int:
 
 def index_to_column(index: int) -> str:
     """
-    Return the column letters of given 0-based index.
+    Return the column letters of specified 0-based index.
 
     Parameters
     ----------
@@ -207,8 +207,8 @@ def index_to_column(index: int) -> str:
 
 def cell_range_values(sheet: xlrd.sheet.Sheet, cell_range: str) -> List[str]:
     """
-    Return given workbook sheet cell range values, i.e., the values of the
-    rows and columns for given cell range.
+    Return specified workbook sheet cell range values, i.e., the values of the
+    rows and columns for specified cell range.
 
     Parameters
     ----------