chore: update fileset docstrings (#621)

Signed-off-by: Callahan Kovacs <[email protected]>

craft_parts/executor/filesets.py

@@ -1,6 +1,6 @@
 # -*- Mode:Python; indent-tabs-mode:nil; tab-width:4 -*-
 #
-# Copyright 2015-2021 Canonical Ltd.
+# Copyright 2015-2021,2024 Canonical Ltd.
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -25,9 +25,18 @@
 
 
 class Fileset:
-    """Helper class to process string lists."""
+    """A class that represents a list of filepath strings to include or exclude.
+
+    Filepaths to include do not begin with a hyphen.
+    Filepaths to exclude begin with a hyphen.
+    """
 
     def __init__(self, entries: List[str], *, name: str = "") -> None:
+        """Initialize a fileset.
+
+        :param entries: List of filepaths represented as strings.
+        :param name: Name of the fileset.
+        """
         self._name = name
         self._list = entries
 
@@ -90,12 +99,12 @@ def combine(self, other: "Fileset") -> None:
 
 
 def migratable_filesets(fileset: Fileset, srcdir: str) -> Tuple[Set[str], Set[str]]:
-    """Return the files and directories that can be migrated.
+    """Determine the files to migrate from a directory based on a fileset.
 
-    :param fileset: The fileset to migrate.
+    :param fileset: The fileset used to filter files in the srcdir.
+    :param srcdir: Directory containing files to migrate.
 
-    :return: A tuple containing the set of files and the set of directories
-        that can be migrated.
+    :return: A tuple containing the set of files and the set of directories to migrate.
     """
     includes, excludes = _get_file_list(fileset)
 

craft_parts/executor/organize.py

@@ -1,6 +1,6 @@
 # -*- Mode:Python; indent-tabs-mode:nil; tab-width:4 -*-
 #
-# Copyright 2015-2021 Canonical Ltd.
+# Copyright 2015-2021,2024 Canonical Ltd.
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU Lesser General Public
@@ -38,11 +38,15 @@ def organize_files(
 ) -> None:
     """Rearrange files for part staging.
 
-    :param fileset: A fileset containing the `organize` file mapping.
-    :param base_dir: Where the installed files are located.
+    :param part_name: The name of the part to organize files for.
+    :param mapping: A mapping of source filepaths to destination filepaths.
+    :param base_dir: Directory containing files to organize.
     :param overwrite: Whether existing files should be overwritten. This is
         only used in build updates, when a part may organize over files
         it previously organized.
+
+    :raises FileOrganizeError: If the destination file already exists or multiple files
+        are organized to the same destination.
     """
     for key in sorted(mapping, key=lambda x: ["*" in x, x]):
         src = os.path.join(base_dir, path_utils.get_partitioned_path(key))