standardize doc strings

janosh · janosh · commit 2a35841f37dc · 2024-08-03T09:59:57.000-04:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -2,7 +2,7 @@ exclude: ^(docs|tests/files|tasks.py)
 
 ci:
   autoupdate_schedule: monthly
-  skip: [ mypy, pyright ]
+  skip: [mypy, pyright]
   autofix_commit_msg: pre-commit auto-fixes
   autoupdate_commit_msg: pre-commit autoupdate
 
@@ -11,7 +11,7 @@ repos:
     rev: v0.5.6
     hooks:
       - id: ruff
-        args: [ --fix, --unsafe-fixes ]
+        args: [--fix, --unsafe-fixes]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -30,16 +30,16 @@ repos:
     rev: v2.3.0
     hooks:
       - id: codespell
-        stages: [ commit, commit-msg ]
-        exclude_types: [ html ]
-        additional_dependencies: [ tomli ] # needed to read pyproject.toml below py3.11
+        stages: [commit, commit-msg]
+        exclude_types: [html]
+        additional_dependencies: [tomli] # needed to read pyproject.toml below py3.11
         exclude: src/pymatgen/analysis/aflow_prototypes.json
 
   - repo: https://github.com/MarcoGorelli/cython-lint
     rev: v0.16.2
     hooks:
       - id: cython-lint
-        args: [ --no-pycodestyle ]
+        args: [--no-pycodestyle]
       - id: double-quote-cython-strings
 
   - repo: https://github.com/adamchainz/blacken-docs
@@ -56,13 +56,13 @@ repos:
         # MD033: no inline HTML
         # MD041: first line in a file should be a top-level heading
         # MD025: single title
-        args: [ --disable, MD013, MD024, MD025, MD033, MD041, "--" ]
+        args: [--disable, MD013, MD024, MD025, MD033, MD041, "--"]
 
   - repo: https://github.com/kynan/nbstripout
     rev: 0.7.1
     hooks:
       - id: nbstripout
-        args: [ --drop-empty-cells, --keep-output ]
+        args: [--drop-empty-cells, --keep-output]
 
   - repo: https://github.com/RobertCraigie/pyright-python
     rev: v1.1.374
diff --git a/src/pymatgen/alchemy/transmuters.py b/src/pymatgen/alchemy/transmuters.py
@@ -331,13 +331,10 @@ def batch_write_vasp_input(
         output_dir: Directory to output files
         create_directory (bool): Create the directory if not present.
             Defaults to True.
-        subfolder: Function to create subdirectory name from
-            transformed_structure.
-            e.g. lambda x: x.other_parameters["tags"][0] to use the first
-            tag.
-        include_cif (bool): Boolean indication whether to output a CIF as
-            well. CIF files are generally better supported in visualization
-            programs.
+        subfolder: Function to create subdirectory name from transformed_structure.
+            E.g. lambda x: x.other_parameters["tags"][0] to use the first tag.
+        include_cif (bool): Pass True to output a CIF as well. CIF files are generally
+            better supported in visualization programs.
         **kwargs: Any kwargs supported by vasp_input_set.
     """
     for idx, struct in enumerate(transformed_structures):
diff --git a/src/pymatgen/analysis/bond_valence.py b/src/pymatgen/analysis/bond_valence.py
@@ -421,15 +421,15 @@ def _recurse(assigned=None):
             return [[int(frac_site) for frac_site in assigned[site]] for site in structure]
         raise ValueError("Valences cannot be assigned!")
 
-    def get_oxi_state_decorated_structure(self, structure: Structure):
+    def get_oxi_state_decorated_structure(self, structure: Structure) -> Structure:
         """Get an oxidation state decorated structure. This currently works only
         for ordered structures only.
 
         Args:
             structure: Structure to analyze
 
         Returns:
-            A modified structure that is oxidation state decorated.
+            Structure: modified with oxidation state decorations.
 
         Raises:
             ValueError if the valences cannot be determined.
diff --git a/src/pymatgen/analysis/chempot_diagram.py b/src/pymatgen/analysis/chempot_diagram.py
@@ -168,7 +168,7 @@ def get_plot(
                 (in eV/atom), helping provide visual clarity. Defaults to 1.0.
 
         Returns:
-            A Plotly Figure object
+            plotly.graph_objects.Figure
         """
         if elements:
             elems = [Element(str(e)) for e in elements]
diff --git a/src/pymatgen/analysis/diffraction/tem.py b/src/pymatgen/analysis/diffraction/tem.py
@@ -338,16 +338,15 @@ def is_parallel(
         plane: Tuple3Ints,
         other_plane: Tuple3Ints,
     ) -> bool:
-        """
-        Checks if two hkl planes are parallel in reciprocal space.
+        """Checks if two hkl planes are parallel in reciprocal space.
 
         Args:
             structure (Structure): The input structure.
             plane (3-tuple): The first plane to be compared.
             other_plane (3-tuple): The other plane to be compared.
 
         Returns:
-            boolean
+            bool: True if the planes are parallel, False otherwise.
         """
         phi = self.get_interplanar_angle(structure, plane, other_plane)
         return phi in (180, 0) or np.isnan(phi)
diff --git a/src/pymatgen/analysis/local_env.py b/src/pymatgen/analysis/local_env.py
@@ -1161,7 +1161,7 @@ def _is_in_targets(site, targets):
         targets ([Element]) List of elements
 
     Returns:
-        boolean: Whether this site contains a certain list of elements
+        bool: Whether this site contains a certain list of elements
     """
     elems = _get_elements(site)
     return all(elem in targets for elem in elems)
diff --git a/src/pymatgen/analysis/magnetism/jahnteller.py b/src/pymatgen/analysis/magnetism/jahnteller.py
@@ -272,7 +272,7 @@ def is_jahn_teller_active(
                 quite distorted, this threshold is smaller than one might expect
 
         Returns:
-            boolean, True if might be Jahn-Teller active, False if not
+            bool: True if might be Jahn-Teller active, False if not
         """
         active = False
 
diff --git a/src/pymatgen/analysis/molecule_matcher.py b/src/pymatgen/analysis/molecule_matcher.py
@@ -496,7 +496,7 @@ def _is_molecule_linear(self, mol):
             mol: The molecule. OpenBabel OBMol object.
 
         Returns:
-            Boolean value.
+            bool
         """
         if mol.NumAtoms() < 3:
             return True
@@ -589,7 +589,7 @@ def fit(self, mol1, mol2):
             mol2: Second molecule. OpenBabel OBMol or pymatgen Molecule object
 
         Returns:
-            A boolean value indicates whether two molecules are the same.
+            bool: Whether two molecules are the same.
         """
         return self.get_rmsd(mol1, mol2) < self._tolerance
 
diff --git a/src/pymatgen/analysis/phase_diagram.py b/src/pymatgen/analysis/phase_diagram.py
@@ -1573,8 +1573,8 @@ def __init__(
                 the entries themselves and are sorted alphabetically.
                 If specified, element ordering (e.g. for pd coordinates)
                 is preserved.
-            keep_all_spaces (bool): Boolean control on whether to keep chemical spaces
-                that are subspaces of other spaces.
+            keep_all_spaces (bool): Pass True to keep chemical spaces that are subspaces
+                of other spaces.
             verbose (bool): Whether to show progress bar during convex hull construction.
         """
         if elements is None:
diff --git a/src/pymatgen/analysis/reaction_calculator.py b/src/pymatgen/analysis/reaction_calculator.py
@@ -262,7 +262,7 @@ def from_dict(cls, dct: dict) -> Self:
             dct (dict): from as_dict().
 
         Returns:
-            A BalancedReaction object.
+            BalancedReaction
         """
         reactants = {Composition(comp): coeff for comp, coeff in dct["reactants"].items()}
         products = {Composition(comp): coeff for comp, coeff in dct["products"].items()}
diff --git a/src/pymatgen/analysis/structure_analyzer.py b/src/pymatgen/analysis/structure_analyzer.py
@@ -395,7 +395,7 @@ def contains_peroxide(structure, relative_cutoff=1.1):
             atoms must be to each other to be considered a peroxide.
 
     Returns:
-        Boolean indicating if structure contains a peroxide anion.
+        bool: True if structure contains a peroxide anion.
     """
     return oxide_type(structure, relative_cutoff) == "peroxide"
 
diff --git a/src/pymatgen/analysis/structure_matcher.py b/src/pymatgen/analysis/structure_matcher.py
@@ -53,7 +53,7 @@ def are_equal(self, sp1, sp2) -> bool:
                 definition in Site and PeriodicSite.
 
         Returns:
-            Boolean indicating whether species are considered equal.
+            bool: Whether species are considered equal.
         """
         return False
 
@@ -122,7 +122,7 @@ def are_equal(self, sp1, sp2) -> bool:
                 definition in Site and PeriodicSite.
 
         Returns:
-            Boolean indicating whether species are equal.
+            bool: Whether species are equal.
         """
         return sp1 == sp2
 
@@ -151,7 +151,7 @@ def are_equal(self, sp1, sp2) -> bool:
                 definition in Site and PeriodicSite.
 
         Returns:
-            Boolean indicating whether species are equal.
+            bool: Whether species are equal.
         """
         for s1 in sp1:
             spin1 = getattr(s1, "spin", 0) or 0
@@ -188,8 +188,7 @@ def are_equal(self, sp1, sp2) -> bool:
                 definition in Site and PeriodicSite.
 
         Returns:
-            Boolean indicating whether species are the same based on element
-            and amounts.
+            bool: Whether species are the same based on element and amounts.
         """
         comp1 = Composition(sp1)
         comp2 = Composition(sp2)
diff --git a/src/pymatgen/core/lattice.py b/src/pymatgen/core/lattice.py
@@ -1300,8 +1300,7 @@ def dot(
         Args:
             coords_a: Array-like coordinates.
             coords_b: Array-like coordinates.
-            frac_coords (bool): Boolean stating whether the vector
-                corresponds to fractional or Cartesian coordinates.
+            frac_coords (bool): True if the vectors are fractional (as opposed to Cartesian) coordinates.
 
         Returns:
             one-dimensional `numpy` array.
diff --git a/src/pymatgen/electronic_structure/bandstructure.py b/src/pymatgen/electronic_structure/bandstructure.py
@@ -303,7 +303,7 @@ def get_vbm(self) -> dict[str, Any]:
         """Get data about the valence band maximum (VBM).
 
         Returns:
-            dict of keys "band_index", "kpoint_index", "kpoint", "energy":
+            dict with keys "band_index", "kpoint_index", "kpoint", "energy":
                 - "band_index" (dict): A dict with spin keys pointing to a list of the
                 indices of the band containing the VBM (please note that you
                 can have several bands sharing the VBM) {Spin.up:[],
@@ -370,7 +370,7 @@ def get_cbm(self) -> dict[str, Any]:
         """Get data about the conduction band minimum (CBM).
 
         Returns:
-            dict of keys "band_index", "kpoint_index", "kpoint", "energy":
+            dict with keys "band_index", "kpoint_index", "kpoint", "energy":
                 - "band_index" (dict): A dict with spin keys pointing to a list of the
                 indices of the band containing the CBM (please note that you
                 can have several bands sharing the CBM) {Spin.up:[], Spin.down:[]}.
@@ -436,7 +436,7 @@ def get_band_gap(self) -> dict[str, Any]:
         r"""Get band gap.
 
         Returns:
-            dict of keys "energy", "direct", "transition":
+            dict with keys "energy", "direct", "transition":
                 "energy" (float): Band gap energy.
                 "direct" (bool): Whether the gap is direct.
                 "transition" (str): Kpoint labels of the transition (e.g., "\\Gamma-X").
@@ -609,7 +609,7 @@ def from_dict(cls, dct: dict[str, Any]) -> Self:
             dct: A dict with all data for a BandStructure.
 
         Returns:
-            A BandStructure object.
+            BandStructure
         """
         # Strip the label to recover initial string
         # (see trick used in as_dict to handle "$"" chars)
@@ -657,7 +657,7 @@ def from_old_dict(cls, dct: dict[str, Any]) -> Self:
             dct (dict): A dict with all data for a BandStructure object.
 
         Returns:
-            A BandStructure object.
+            BandStructure
         """
         # Strip the label to recover initial string
         # (see trick used in as_dict to handle "$" chars)
diff --git a/src/pymatgen/electronic_structure/boltztrap.py b/src/pymatgen/electronic_structure/boltztrap.py
@@ -1938,7 +1938,7 @@ def from_files(cls, path_dir: str, dos_spin: Literal[-1, 1] = 1) -> Self:
             dos_spin: in DOS mode, set to 1 for spin up and -1 for spin down
 
         Returns:
-            a BoltztrapAnalyzer object
+            BoltztrapAnalyzer
         """
         run_type, warning, efermi, gap, doping_levels = cls.parse_outputtrans(path_dir)
 
diff --git a/src/pymatgen/electronic_structure/cohp.py b/src/pymatgen/electronic_structure/cohp.py
@@ -234,8 +234,8 @@ class CompleteCohp(Cohp):
     """A wrapper that defines an average COHP, and individual COHPs.
 
     Attributes:
-        are_coops (bool): Whether the object is consisting of COOPs.
-        are_cobis (bool): Whether the object is consisting of COBIs.
+        are_coops (bool): Whether the object consists of COOPs.
+        are_cobis (bool): Whether the object consists of COBIs.
         efermi (float): The Fermi level.
         energies (Sequence[float]): Sequence of energies.
         structure (Structure): Structure associated with the COHPs.
diff --git a/src/pymatgen/electronic_structure/plotter.py b/src/pymatgen/electronic_structure/plotter.py
@@ -3927,8 +3927,7 @@ def plot_fermi_surface(
             By default 0 eV correspond to the VBM, as in the plot of band
             structure along symmetry line.
             Default: One surface, with max energy value + 0.01 eV
-        cbm (bool): Boolean value to specify if the considered band is a
-            conduction band or not
+        cbm (bool): True if the considered band is a conduction band or not.
         multiple_figure (bool): If True a figure for each energy level will be
             shown. If False all the surfaces will be shown in the same figure.
             In this last case, tune the transparency factor.
diff --git a/src/pymatgen/ext/matproj_legacy.py b/src/pymatgen/ext/matproj_legacy.py
@@ -781,7 +781,7 @@ def get_bandstructure_by_material_id(self, material_id, line_mode=True):
                 (default). If False, return the uniform band structure.
 
         Returns:
-            A BandStructure object.
+            BandStructure
         """
         prop = "bandstructure" if line_mode else "bandstructure_uniform"
         data = self.get_data(material_id, prop=prop)
@@ -1577,7 +1577,7 @@ def _check_nomad_exist(url) -> bool:
         return content["pagination"]["total"] != 0
 
     @staticmethod
-    def parse_criteria(criteria_string):
+    def parse_criteria(criteria_string) -> dict:
         """Parse a powerful and simple string criteria and generates a proper
         mongo syntax criteria.
 
diff --git a/src/pymatgen/ext/optimade.py b/src/pymatgen/ext/optimade.py
@@ -508,8 +508,7 @@ def _parse_provider(self, provider: str, provider_url: str) -> dict[str, Provide
             provider_url: An OPTIMADE provider URL
 
         Returns:
-            A dictionary of keys (in format of "provider.database") to
-            Provider objects.
+            dict: keys (in format of "provider.database") mapped to Provider objects.
         """
         # Add trailing slash to all URLs if missing; prevents urljoin from scrubbing
         if urlparse(provider_url).path is not None and not provider_url.endswith("/"):
diff --git a/src/pymatgen/io/lmto.py b/src/pymatgen/io/lmto.py
@@ -281,7 +281,7 @@ class LMTOCopl:
                 "length": bond length}
         efermi (float): The Fermi energy in Ry or eV.
         energies (list): Sequence of energies in Ry or eV.
-        is_spin_polarized (bool): Boolean to indicate if the calculation is spin polarized.
+        is_spin_polarized (bool): True if the calculation is spin-polarized.
     """
 
     def __init__(self, filename="COPL", to_eV=False):
diff --git a/src/pymatgen/io/lobster/outputs.py b/src/pymatgen/io/lobster/outputs.py
diff --git a/src/pymatgen/io/vasp/outputs.py b/src/pymatgen/io/vasp/outputs.py
diff --git a/src/pymatgen/io/vasp/sets.py b/src/pymatgen/io/vasp/sets.py
diff --git a/src/pymatgen/io/wannier90.py b/src/pymatgen/io/wannier90.py
diff --git a/src/pymatgen/phonon/plotter.py b/src/pymatgen/phonon/plotter.py
diff --git a/src/pymatgen/transformations/standard_transformations.py b/src/pymatgen/transformations/standard_transformations.py
diff --git a/src/pymatgen/util/provenance.py b/src/pymatgen/util/provenance.py
