From 389ceb8ec97eaffb3bb7f3a1a707e2b85d5caf48 Mon Sep 17 00:00:00 2001
From: Victoria <112418493+veni-vidi-vici-dormivi@users.noreply.github.com>
Date: Tue, 7 Jan 2025 13:40:45 +0100
Subject: [PATCH] Extend documentation of FileFinder and FileContainer (#141)

* extend documentation of FileFinder and FileContainer

* add meta, paths and items to api.rst

* CHANGELOG

* run velin
---
 CHANGELOG.md              |  3 +--
 docs/source/api.rst       |  3 +++
 filefisher/_filefinder.py | 50 +++++++++++++++++++++++++++++----------
 3 files changed, 42 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c1c74a5..397a6a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,7 @@
 
 ## v0.4.0 - unreleased
 - Added documentation files for readthedocs ([#134](https://github.com/mpytools/filefisher/pull/134))
-  and extended the documentation with usage ([#135](https://github.com/mpytools/filefisher/pull/135)),
-  and installation instructions ([#136](https://github.com/mpytools/filefisher/pull/136))
+  and extended the documentation with usage ([#135](https://github.com/mpytools/filefisher/pull/135)), installation instructions ([#136](https://github.com/mpytools/filefisher/pull/136)), as well as extension of the api documentation ([#141](https://github.com/mpytools/filefisher/pull/141))
 - Added two methods to find _exactly_ one file or path (and raise an error otherwise):
   `FileFinder.find_single_file` and `FileFinder.find_single_path`
   ([#101](https://github.com/mpytools/filefisher/pull/101)).
diff --git a/docs/source/api.rst b/docs/source/api.rst
index d156ed8..1837a89 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -29,6 +29,9 @@ FileContainer
    :toctree: generated/
 
    ~FileContainer
+   ~FileContainer.meta
+   ~FileContainer.paths
+   ~FileContainer.items
    ~FileContainer.search
    ~FileContainer.concat
 
diff --git a/filefisher/_filefinder.py b/filefisher/_filefinder.py
index 05efefc..48845ab 100644
--- a/filefisher/_filefinder.py
+++ b/filefisher/_filefinder.py
@@ -534,7 +534,8 @@ def find_single_path(self, keys=None, **keys_kwargs) -> "FileContainer":
 
         Raises
         ------
-        ValueError : if more or less than one path is found
+        ValueError
+            if more or less than one path is found.
         """
 
         return self.path.find_single(keys, **keys_kwargs)
@@ -557,7 +558,8 @@ def find_single_file(self, keys=None, **keys_kwargs) -> "FileContainer":
 
         Raises
         ------
-        ValueError : if more or less than one file is found
+        ValueError
+            if more or less than one file is found.
         """
 
         return self.full.find_single(keys, **keys_kwargs)
@@ -585,14 +587,6 @@ def __init__(self, df: pd.DataFrame):
         ----------
         df : pd.DataFrame
             DataFrame with info about found paths from FileFinder.
-
-        Properties
-        ----------
-        meta : list[dict[str, Any]]
-            List of metadata dictionaries.
-        paths : list[str]
-            List of paths.
-            
         """
 
         self.df = df
@@ -623,17 +617,35 @@ def __getitem__(self, key):
 
     @property
     def meta(self) -> list[dict[str, Any]]:
+        """Return metadata as list of dictionaries"""
         return self.df.to_dict("records")
 
     @property
     def paths(self) -> list[str]:
+        """Return paths as list"""
         return self.df.index.to_list()
 
     def items(self) -> Generator[tuple[str, dict[str, Any]], None, None]:
+        """Return a generator of (path, metadata) tuples"""
         for index, element in self.df.iterrows():
             yield index, element.to_dict()
 
     def combine_by_key(self, keys=None, sep="."):
+        """combine columns
+
+        Parameters
+        ----------
+        keys : list[str], optional
+            List of keys to combine. If None, all keys are combined.
+        sep : str, default "."
+            Separator between the keys.
+
+        Returns
+        -------
+        pd.Series
+            pd.Series with combined columns where the keys are seperated by `sep`.
+
+        """
         warnings.warn(
             "`combine_by_key` has been deprecated and will be removed in a future version",
             FutureWarning,
@@ -642,7 +654,21 @@ def combine_by_key(self, keys=None, sep="."):
         return self._combine_by_keys(keys=keys, sep=sep)
 
     def _combine_by_keys(self, keys=None, sep="."):
-        """combine columns"""
+        """combine columns
+
+        Parameters
+        ----------
+        keys : list[str], optional
+            List of keys to combine. If None, all keys are combined.
+        sep : str, default "."
+            Separator between the keys.
+
+        Returns
+        -------
+        pd.Series
+            pd.Series with combined columns where the keys are seperated by `sep`.
+
+        """
 
         if keys is None:
             keys = list(self.df.columns)
@@ -654,7 +680,7 @@ def search(self, **query):
 
         Parameters
         ----------
-        **query: Mapping[str, str | int | list[str | int]]
+        **query : Mapping[str, str | int | list[str | int]]
             Search query.
 
         Notes