docs: address PEP 257 docstring conventions across the codebase (#760)

* docs: add missing magic-method docstrings across codebase

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: geritwagner

colrev/constants.py

@@ -425,9 +425,11 @@ class RecordState(Enum):
     # Note : TBD: rev_coded
 
     def __str__(self) -> str:
+        """Return a string representation."""
         return f"{self.name}"
 
     def __lt__(self, other) -> bool:  # type: ignore
+        """Return whether this instance is less than another."""
         if self.__class__ == RecordState and other.__class__ == RecordState:
             return self.value < other.value
         raise NotImplementedError
@@ -593,6 +595,7 @@ class OperationsType(Enum):
     check = "check"
 
     def __str__(self) -> str:
+        """Return a string representation."""
         return f"{self.name}"
 
     @classmethod
@@ -625,6 +628,7 @@ class SortedEnumMeta(EnumMeta):
     def __init__(
         cls, name: str, bases: typing.Tuple[type, ...], classdict: dict
     ) -> None:
+        """Initialize the instance."""
         super().__init__(name, bases, classdict)
         # Sort the members by their values
         # pylint: disable=unsubscriptable-object
@@ -652,9 +656,11 @@ def get_options(cls) -> typing.List[str]:
         return cls._member_names_
 
     def __str__(self) -> str:
+        """Return a string representation."""
         return self.name
 
     def __lt__(self, other: "SearchType") -> bool:
+        """Return whether this instance is less than another."""
         if isinstance(other, SearchType):
             return self.value < other.value
         return NotImplemented
@@ -670,6 +676,7 @@ class SearchSourceHeuristicStatus(Enum):
     todo = "to_be_implemented"
 
     def __str__(self) -> str:
+        """Return a string representation."""
         return f"{self.name}"  # pragma: no cover
 
 
@@ -701,6 +708,7 @@ def get_options(cls) -> typing.List[str]:
         return cls._member_names_
 
     def __str__(self) -> str:
+        """Return a string representation."""
         return self.name
 
 

colrev/dataset.py

@@ -28,6 +28,7 @@ class Dataset:
     """The CoLRev dataset (records and their history in git)."""
 
     def __init__(self, *, review_manager: colrev.review_manager.ReviewManager) -> None:
+        """Initialize the instance."""
         self.review_manager = review_manager
 
     @cached_property

colrev/env/environment_manager.py

@@ -26,6 +26,7 @@ class EnvironmentManager:
     load_yaml = False
 
     def __init__(self) -> None:
+        """Initialize the instance."""
         self.environment_registry = self.load_environment_registry()
         self._registered_ports: typing.List[str] = []
 

colrev/env/grobid_service.py

@@ -21,6 +21,7 @@ class GrobidService:
     GROBID_IMAGE = "lfoppiano/grobid:0.8.2"
 
     def __init__(self) -> None:
+        """Initialize the instance."""
         colrev.env.docker_manager.DockerManager.build_docker_image(
             imagename=self.GROBID_IMAGE
         )

colrev/env/language_service.py

@@ -24,7 +24,7 @@ def __init__(self) -> None:
         # It performs particularly well for short strings (single words/word pairs)
         # The langdetect library is non-deterministic, especially for short strings
         # https://pypi.org/project/langdetect/
-
+        """Initialize the instance."""
         self._lingua_language_detector = (
             LanguageDetectorBuilder.from_all_languages_with_latin_script().build()
         )

colrev/env/local_index.py

@@ -31,6 +31,7 @@ def __init__(
         index_tei: bool = False,
         verbose_mode: bool = False,
     ) -> None:
+        """Initialize the instance."""
         self.verbose_mode = verbose_mode
         self.environment_manager = colrev.env.environment_manager.EnvironmentManager()
         self._index_tei = index_tei

colrev/env/local_index_builder.py

@@ -44,6 +44,7 @@ def __init__(
         index_tei: bool = False,
         verbose_mode: bool = False,
     ) -> None:
+        """Initialize the instance."""
         self.verbose_mode = verbose_mode
         self.environment_manager = colrev.env.environment_manager.EnvironmentManager()
         self._index_tei = index_tei

colrev/env/local_index_sqlite.py

@@ -54,6 +54,7 @@ class SQLiteIndex:
     def __init__(
         self, *, index_name: str, index_keys: list, reinitialize: bool
     ) -> None:
+        """Initialize the instance."""
         self.index_name = index_name
         self.index_keys = index_keys
         self.connection = sqlite3.connect(
@@ -152,6 +153,7 @@ class SQLiteIndexRecord(SQLiteIndex):
             WHERE {LocalIndexFields.ID}=?"""
 
     def __init__(self, *, reinitialize: bool = False) -> None:
+        """Initialize the instance."""
         super().__init__(
             index_name=self.INDEX_NAME,
             index_keys=self.KEYS,
@@ -266,6 +268,7 @@ class SQLiteIndexRankings(SQLiteIndex):
     SELECT_QUERY = f"SELECT * FROM {INDEX_NAME} WHERE journal_name = ?"
 
     def __init__(self, *, reinitialize: bool = False) -> None:
+        """Initialize the instance."""
         super().__init__(
             index_name=self.INDEX_NAME,
             index_keys=self.KEYS,
@@ -306,6 +309,7 @@ class SQLiteIndexTOC(SQLiteIndex):
     INSERT_MANY_QUERY = f"INSERT INTO {INDEX_NAME} VALUES(?, ?)"
 
     def __init__(self, *, reinitialize: bool = False) -> None:
+        """Initialize the instance."""
         super().__init__(
             index_name=self.INDEX_NAME,
             index_keys=self.KEYS,