From fb04676aeff0698570421d74a6cb659c57f979cc Mon Sep 17 00:00:00 2001
From: Fabien Lelaquais <86590727+FabienLelaquais@users.noreply.github.com>
Date: Tue, 1 Oct 2024 19:01:15 +0200
Subject: [PATCH] Minor doc improvements. (#1875)

* Minor doc improvements.

* more changes
---
 doc/gui/examples/controls/selector_filter.py | 17 ++++--
 doc/gui/examples/controls/selector_icon.py   | 10 ++--
 taipy/gui/gui.py                             | 55 +++++++++++++-------
 taipy/gui/state.py                           | 13 +++--
 taipy/gui/viselements.json                   |  2 +-
 5 files changed, 67 insertions(+), 30 deletions(-)

diff --git a/doc/gui/examples/controls/selector_filter.py b/doc/gui/examples/controls/selector_filter.py
index 8eb6a28dcd..a18faac2e2 100644
--- a/doc/gui/examples/controls/selector_filter.py
+++ b/doc/gui/examples/controls/selector_filter.py
@@ -14,14 +14,25 @@
 #     python <script>
 # -----------------------------------------------------------------------------------------
 import builtins
+import inspect
 
 from taipy.gui import Gui
 
-_python_builtins = dir(builtins)
-value = _python_builtins[0]
+# Create a list of Python builtins that:
+# - Are callable (i.e. functions)
+# - Are not classes (i.e. Exceptions)
+# - Do not start with "_" (i.e. internals)
+builtin_python_functions = [
+    func
+    for func in dir(builtins)
+    if callable(getattr(builtins, func)) and not inspect.isclass(getattr(builtins, func)) and not func.startswith("_")
+]
+
+# Initialize the bound value to the first Python builtin function
+selection = builtin_python_functions[0]
 
 page = """
-<|{value}|selector|lov={_python_builtins}|filter|multiple|>
+<|{selection}|selector|lov={builtin_python_functions}|filter|multiple|>
 """
 
 if __name__ == "__main__":
diff --git a/doc/gui/examples/controls/selector_icon.py b/doc/gui/examples/controls/selector_icon.py
index e8df6564e8..a1ee419f02 100644
--- a/doc/gui/examples/controls/selector_icon.py
+++ b/doc/gui/examples/controls/selector_icon.py
@@ -13,12 +13,16 @@
 # Python environment and run:
 #     python <script>
 # -----------------------------------------------------------------------------------------
-from taipy.gui import Gui
+from taipy.gui import Gui, Icon
 
 sel = "id2"
-
+lov = [
+    ("id1", "Framework X"),
+    ("id2", Icon("https://docs.taipy.io/en/latest/assets/images/favicon.png", "Taipy")),
+    ("id3", "Framework Y"),
+]
 page = """
-<|{sel}|selector|lov={[("id1", "Label 1"), ("id2", Icon("/images/icon.png", "Label 2"),("id3", "Label 3")]}|>
+<|{sel}|selector|lov={lov}|>
 """
 
 if __name__ == "__main__":
diff --git a/taipy/gui/gui.py b/taipy/gui/gui.py
index 1fc7db45aa..d342859606 100644
--- a/taipy/gui/gui.py
+++ b/taipy/gui/gui.py
@@ -1551,7 +1551,7 @@ def invoke_callback(
             callback (Callable[[State^, ...], None]): The user-defined function that is invoked.<br/>
                 The first parameter of this function **must** be a `State^`.
             args (Optional[Sequence]): The remaining arguments, as a List or a Tuple.
-            module_context (Optional[str]): the name of the module that will be used.
+            module_context (Optional[str]): The name of the module that will be used.
         """  # noqa: E501
         this_sid = None
         if request:
@@ -1703,10 +1703,20 @@ def _get_adapted_lov(self, lov: list, var_type: str):
     def table_on_edit(self, state: State, var_name: str, payload: t.Dict[str, t.Any]):
         """Default implementation of the `on_edit` callback for tables.
 
+           This function sets the value of a specific cell in the tabular dataset stored in
+           *var_name*, typically bound to the *data* property of a table control.
+
         Arguments:
             state: the state instance received in the callback.
             var_name: the name of the variable bound to the table's *data* property.
-            payload: the payload dictionary as it was received from the `on_edit` callback.
+            payload: the payload dictionary received from the `on_edit` callback.<br/>
+                This dictionary has the following keys:
+
+                - *"index"*: The row index of the cell to be modified.
+                - *"col"*: Specifies the name of the column of the cell to be modified.
+                - *"value"*: Specifies the new value to be assigned to the cell.
+                - *"user_value"*: Contains the text entered by the user.
+                - *"tz"*: Specifies the timezone to be used, if applicable.
         """
         try:
             setattr(state, var_name, self._get_accessor().on_edit(getattr(state, var_name), payload))
@@ -1718,13 +1728,16 @@ def table_on_add(
     ):
         """Default implementation of the `on_add` callback for tables.
 
+        This function creates a new row in the tabular dataset stored in *var_name*.<br/>
+        The row is added at the index specified in *payload["index"]*.
+
         Arguments:
-            state: the state instance received in the callback.
-            var_name: the name of the variable bound to the table's *data* property.
-            payload: the payload dictionary as it was received from the `on_add` callback.
-            new_row: the initial values to be stored in the new row.<br/>
-                This defaults to all values being set to 0, whatever that means depending on the
-                column data type.
+            state: The state instance received from the callback.
+            var_name: The name of the variable bound to the table's *data* property.
+            payload: The payload dictionary received from the `on_add` callback.
+            new_row: The initial values for the new row.<br/>
+                If this parameter is not specified, the new row is initialized with all values set
+                to 0, with the exact meaning depending on the column data type.
         """
         try:
             setattr(state, var_name, self._get_accessor().on_add(getattr(state, var_name), payload, new_row))
@@ -1734,10 +1747,13 @@ def table_on_add(
     def table_on_delete(self, state: State, var_name: str, payload: t.Dict[str, t.Any]):
         """Default implementation of the `on_delete` callback for tables.
 
+        This function removes a row from the tabular dataset stored in *var_name*.<br/>
+        The row to be removed is located at the index specified in *payload["index"]*.
+
         Arguments:
-            state: the state instance received in the callback.
-            var_name: the name of the variable bound to the table's *data* property.
-            payload: the payload dictionary as it was received from the `on_delete` callback.
+            state: The state instance received in the callback.
+            var_name: The name of the variable bound to the table's *data* property.
+            payload: The payload dictionary received from the `on_delete` callback.
         """
         try:
             setattr(state, var_name, self._get_accessor().on_delete(getattr(state, var_name), payload))
@@ -1923,9 +1939,9 @@ def add_page(
                   Markdown text.
             style (Optional[str]): Additional CSS style to apply to this page.
 
-                - if there is style associated with a page, it is used at a global level
-                - if there is no style associated with the page, the style is cleared at a global level
-                - if the page is embedded in a block control, the style is ignored
+                - If there is style associated with a page, it is used at a global level
+                - If there is no style associated with the page, the style is cleared at a global level
+                - If the page is embedded in a block control, the style is ignored
 
         Note that page names cannot start with the slash ('/') character and that each
         page must have a unique name.
@@ -2836,15 +2852,16 @@ def _get_authorization(self, client_id: t.Optional[str] = None, system: t.Option
     def set_favicon(self, favicon_path: t.Union[str, Path], state: t.Optional[State] = None):
         """Change the favicon for all clients.
 
-        This function dynamically changes the favicon of Taipy GUI pages for a single or all
-        connected clients.
+        This function dynamically changes the favicon (the icon associated with the application's
+        pages) of Taipy GUI pages for a single or all connected clients.
         Note that the *favicon* parameter to `(Gui.)run()^` can also be used to change
-         the favicon when the application starts.
+        the favicon when the application starts.
 
         Arguments:
-            favicon_path: the path to the image file to use.<br/>
+            favicon_path: The path to the image file to use.<br/>
                 This can be expressed as a path name or a URL (relative or not).
-            state: the state to apply the change to.
+            state: The state to apply the change to.<br/>
+                If no set or set to None, all the application's clients are impacted.
         """
         if state or self.__favicon != favicon_path:
             if not state:
diff --git a/taipy/gui/state.py b/taipy/gui/state.py
index dc0e7124c7..d188fe19f0 100644
--- a/taipy/gui/state.py
+++ b/taipy/gui/state.py
@@ -251,9 +251,14 @@ def __exit__(self, exc_type, exc_value, traceback):
     def set_favicon(self, favicon_path: t.Union[str, Path]):
         """Change the favicon for the client of this state.
 
-        This function dynamically changes the favicon of Taipy GUI pages for a specific client.
-        favicon_path can be an URL (relative or not) or a file path.
-        TODO The *favicon* parameter to `(Gui.)run()^` can also be used to change
-         the favicon when the application starts.
+        This function dynamically changes the favicon (the icon associated with the application's
+        pages) of Taipy GUI pages for the specific client of this state.
+
+        Note that the *favicon* parameter to `(Gui.)run()^` can also be used to change
+        the favicon when the application starts.
+
+        Arguments:
+            favicon_path: The path to the image file to use.<br/>
+                This can be expressed as a path name or a URL (relative or not).
         """
         super().__getattribute__(State.__gui_attr).set_favicon(favicon_path, self)
diff --git a/taipy/gui/viselements.json b/taipy/gui/viselements.json
index 2a406e5fbd..c4f87e533f 100644
--- a/taipy/gui/viselements.json
+++ b/taipy/gui/viselements.json
@@ -1990,7 +1990,7 @@
                         "name": "adapter",
                         "type": "Union[str, Callable]",
                         "default_value": "<tt>lambda x: str(x)</tt>",
-                        "doc": "A function or the name of the function  that transforms an element of <i>lov</i> into a <i>tuple(id:str, label:Union[str,Icon])</i>.<br/>The default value is a function that returns the string representation of the <i>lov</i> element."
+                        "doc": "A function or the name of the function that transforms an element of <i>lov</i> into a <i>tuple(id:str, label:Union[str,Icon])</i>.<br/>The default value is a function that returns the string representation of the <i>lov</i> element."
                     },
                     {
                         "name": "type",