docs: docs review

src/ahriman/application/application/application.py

@@ -109,7 +109,8 @@ class Application(ApplicationPackages, ApplicationRepository):
 
     def with_dependencies(self, packages: list[Package], *, process_dependencies: bool) -> list[Package]:
         """
-        add missing dependencies to list of packages
+        add missing dependencies to list of packages. This will extract known packages, check dependencies of
+        the supplied packages and add packages which are not presented in the list of known packages.
 
         Args:
             packages(list[Package]): list of source packages of which dependencies have to be processed
@@ -118,6 +119,14 @@ class Application(ApplicationPackages, ApplicationRepository):
         Returns:
             list[Package]: updated packages list. Packager for dependencies will be copied from
             original package
+
+        Examples:
+            In the most cases, in order to avoid build failure, it is required to add missing packages, which can be
+            done by calling::
+
+                >>> application = ...
+                >>> packages = application.with_dependencies(packages, process_dependencies=True)
+                >>> application.print_updates(packages, log_fn=print)
         """
         def missing_dependencies(source: Iterable[Package]) -> dict[str, str | None]:
             # append list of known packages with packages which are in current sources

src/ahriman/application/application/application_repository.py

@@ -51,7 +51,7 @@ class ApplicationRepository(ApplicationProperties):
 
     def clean(self, *, cache: bool, chroot: bool, manual: bool, packages: bool, pacman: bool) -> None:
         """
-        run all clean methods. Warning: some functions might not be available under non-root
+        run all clean methods. Warning: some functions might not be available for non-root user
 
         Args:
             cache(bool): clear directory with package caches
@@ -142,7 +142,11 @@ class ApplicationRepository(ApplicationProperties):
     def update(self, updates: Iterable[Package], packagers: Packagers | None = None, *,
                bump_pkgrel: bool = False) -> Result:
         """
-        run package updates
+        run package updates. This method will separate update in the several steps:
+
+            #. Check already built packages.
+            #. Construct builder instance.
+            #. Delegate build process to the builder instance (either remote or local).
 
         Args:
             updates(Iterable[Package]): list of packages to update

src/ahriman/application/application/workers/remote_updater.py

@@ -126,7 +126,7 @@ class RemoteUpdater(Updater):
             Result: update result
         """
         payload = {
-            "increment": bump_pkgrel,
+            "increment": False,  # force disable increment because it doesn't work yet
             "packager": packagers.default if packagers is not None else None,
             "packages": [package.base for package in updates],
             "patches": [],  # might be used later

src/ahriman/application/lock.py

@@ -135,12 +135,12 @@ class Lock(LazyLogging):
         """
         default workflow is the following:
 
-            1. Check user UID
-            2. Check if there is lock file
-            3. Check web status watcher status
-            4. Wait for lock file to be free
-            5. Create lock file and directory tree
-            6. Report to status page if enabled
+            #. Check user UID
+            #. Check if there is lock file
+            #. Check web status watcher status
+            #. Wait for lock file to be free
+            #. Create lock file and directory tree
+            #. Report to status page if enabled
 
         Returns:
             Self: always instance of self

src/ahriman/core/alpm/remote/remote.py

@@ -32,7 +32,7 @@ class Remote(SyncHttpClient):
 
             >>> from ahriman.core.alpm.remote import AUR, Official
             >>>
-            >>> package = AUR.info("ahriman", pacman=pacman)
+            >>> package = AUR.info("ahriman")
             >>> search_result = Official.multisearch("pacman", "manager", pacman=pacman)
 
         Differnece between :func:`search()` and :func:`multisearch()` is that :func:`search()` passes all arguments to

src/ahriman/core/alpm/repo.py

@@ -76,7 +76,7 @@ class Repo(LazyLogging):
 
     def init(self) -> None:
         """
-        create empty repository database
+        create empty repository database. It just calls add with empty arguments
         """
         check_output("repo-add", *self.sign_args, str(self.repo_path),
                      cwd=self.paths.repository, logger=self.logger, user=self.uid)

src/ahriman/core/build_tools/sources.py

@@ -32,7 +32,7 @@ from ahriman.models.repository_paths import RepositoryPaths
 
 class Sources(LazyLogging):
     """
-    helper to download package sources (PKGBUILD etc...)
+    helper to download package sources (PKGBUILD etc...) and perform some operations with git
 
     Attributes:
         DEFAULT_BRANCH(str): (class attribute) default branch to process git repositories.