envvars-dialog: small refactor to improve documentation

* Move non-obvious code blocks into methods to better describe why it is needed
* Update all comments

bottles/frontend/utils/gtk.py

@@ -30,28 +30,35 @@ def validate_entry(entry, extend=None) -> bool:
         var_assignment = entry.get_text()
         var_name = ShUtils.split_assignment(var_assignment)[0]
         if var_name and not ShUtils.is_name(var_name):
-            entry.set_show_apply_button(False)
-            entry.set_show_apply_button(True)
+            GtkUtils.reset_entry_apply_button(entry)
             entry.add_css_class("error")
             return False
 
         if not var_name or "=" not in var_assignment:
-            entry.set_show_apply_button(False)
-            entry.set_show_apply_button(True)
+            GtkUtils.reset_entry_apply_button(entry)
             entry.remove_css_class("error")
             return False
 
         if extend is not None:
             if not extend(var_name):
-                entry.set_show_apply_button(False)
-                entry.set_show_apply_button(True)
+                GtkUtils.reset_entry_apply_button(entry)
                 entry.add_css_class("error")
                 return False
 
         entry.set_show_apply_button(True)
         entry.remove_css_class("error")
         return True
 
+    @staticmethod
+    def reset_entry_apply_button(entry) -> None:
+        """
+        Reset the apply_button within AdwEntryRow to hide it without disabling
+        the functionality. This is needed because the widget does not provide
+        an API to control when the button is displayed without disabling it
+        """
+        entry.set_show_apply_button(False)
+        entry.set_show_apply_button(True)
+
     @staticmethod
     def run_in_main_loop(func):
         @wraps(func)

bottles/frontend/windows/envvars.py

@@ -47,6 +47,15 @@ def __init__(self, parent, env, **kwargs):
         self.connect("apply", self.__save)
         self.btn_remove.connect("clicked", self.__remove)
 
+        self.__customize_layout()
+
+    def __customize_layout(self):
+        """
+        Align text input field vertically. Hide unused labels and make layout
+        changes as needed to display the text correctly. We manually traverse
+        AdwEntryRow's widget tree to make these changes because it does not
+        offer options for these customizations on its public API
+        """
         try:
             widget = (
                 self.get_child().get_first_child().get_next_sibling().get_first_child()
@@ -66,8 +75,8 @@ def __init__(self, parent, env, **kwargs):
 
     def __save(self, *_args):
         """
-        Change the env var value according to the
-        user input and update the bottle configuration
+        Change the environment variable value according to the user input and
+        update the bottle configuration
         """
         if not self.__valid_name:
             return
@@ -86,16 +95,14 @@ def __save(self, *_args):
 
     def __remove(self, *_args):
         """
-        Remove the env var from the bottle configuration and
+        Remove the environment variable from the bottle configuration and
         destroy the widget
         """
         self.__remove_config()
         self.parent.remove_entry(self)
 
     def __remove_config(self, *_args):
-        """
-        Remove the env var from the bottle configuration
-        """
+        """Remove the environment variable from the bottle configuration"""
         self.manager.update_config(
             config=self.config,
             key=self.env[0],
@@ -145,10 +152,7 @@ def __validate(self, *_args):
         )
 
     def __save_var(self, *_args):
-        """
-        This function save the new env var to the
-        bottle configuration
-        """
+        """Save the new environment variable to the bottle configuration"""
         if not self.__valid_name:
             return
 
@@ -174,8 +178,8 @@ def __set_description(self):
 
     def __populate_vars_list(self):
         """
-        This function populate the list of env vars
-        with the existing ones from the bottle configuration
+        Populate the list of environment variables with the existing ones from
+        the bottle configuration
         """
         envs = self.config.Environment_Variables.items()
         self.__set_description()