From fe339527336b7067e5c0a107f4350a844b095945 Mon Sep 17 00:00:00 2001
From: Adriaan de Groot <groot@kde.org>
Date: Mon, 30 Sep 2019 12:58:56 +0200
Subject: [PATCH] [displaymanager] Document the internal functions for DE
 finding

 - rename find_* to _search_* to make clear they're internal.
---
 src/modules/displaymanager/main.py | 43 +++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/src/modules/displaymanager/main.py b/src/modules/displaymanager/main.py
index d08b1f049..abbd6b7e8 100644
--- a/src/modules/displaymanager/main.py
+++ b/src/modules/displaymanager/main.py
@@ -51,31 +51,59 @@ class DesktopEnvironment:
         self.executable = exec
         self.desktop_file = desktop
 
-    def find_executable(self, root_mount_point, command):
-        if command.startswith("/"):
+    def _search_executable(self, root_mount_point, pathname):
+        """
+        Search for @p pathname within @p root_mount_point .
+        If the pathname is absolute, just check there inside
+        the target, otherwise earch in a sort-of-sensible $PATH.
+
+        Returns the full (including @p root_mount_point) path
+        to that executable, or None.
+        """
+        if pathname.startswith("/"):
             path = [""]
         else:
             path = ["/bin/", "/usr/bin/", "/sbin/", "/usr/local/bin/"]
 
         for p in path:
-            absolute_path = "{!s}{!s}{!s}".format(root_mount_point, p, command)
+            absolute_path = "{!s}{!s}{!s}".format(root_mount_point, p, pathname)
             if os.path.exists(absolute_path):
                 return absolute_path
         return None
 
-    def find_tryexec(self, root_mount_point, absolute_desktop_file):
+    def _search_tryexec(self, root_mount_point, absolute_desktop_file):
+        """
+        Check @p absolute_desktop_file for a TryExec line and, if that is
+        found, search for the command (executable pathname) within
+        @p root_mount_point. The .desktop file must live within the
+        target root.
+
+        Returns the full (including @p root_mount_point) for the executable
+        from TryExec, or None.
+        """
         assert absolute_desktop_file.startswith(root_mount_point)
         with open(absolute_desktop_file, "r") as f:
             for tryexec_line in [x for x in f.readlines() if x.startswith("TryExec")]:
                 try:
                     key, value = tryexec_line.split("=")
                     if key.strip() == "TryExec":
-                        return self.find_executable(root_mount_point, value.strip())
+                        return self._search_executable(root_mount_point, value.strip())
                 except:
                     pass
         return None
 
+    def find_executable(self, root_mount_point):
+        """
+        Returns the full path of the configured executable within @p root_mount_point,
+        or None if it isn't found. May search in a semi-sensible $PATH.
+        """
+        return self._search_executable(root_mount_point, self.executable)
+
     def find_desktop_file(self, root_mount_point):
+        """
+        Returns the full path of the .desktop file within @p root_mount_point,
+        or None if it isn't found.  Searches both X11 and Wayland sessions.
+        """
         x11_sessions = "{!s}/usr/share/xsessions/{!s}.desktop".format(root_mount_point, self.desktop_file)
         wayland_sessions = "{!s}/usr/share/wayland-sessions/{!s}.desktop".format(root_mount_point, self.desktop_file)
         for candidate in (x11_sessions, wayland_sessions):
@@ -92,8 +120,9 @@ class DesktopEnvironment:
         if desktop_file is None:
             return False
 
-        return (self.find_executable(root_mount_point, self.executable) is not None or
-                self.find_tryexec(root_mount_point, desktop_file) is not None)
+        return (self.find_executable(root_mount_point) is not None or
+                self._search_tryexec(root_mount_point, desktop_file) is not None)
+
 
 
 # This is the list of desktop environments that Calamares looks