docs: python: abi_regex: do some improvements at documentation

Add documentation for two consts and ensure that all sentenses will end with a dot.

Mauro Carvalho Chehab committed 9 months ago

Commit ff916371 parent 66c3bf91 file · +20 −6Browse files

Showing the changes to tools/lib/python (1 of 1 file). Show all

Unified · Split

 from abi.helpers import AbiDebug
 class AbiRegex(AbiParser):
-    """Extends AbiParser to search ABI nodes with regular expressions"""
+    """
+    Extends AbiParser to search ABI nodes with regular expressions.
-    # Escape only ASCII visible characters
+    There some optimizations here to allow a quick symbol search:
+    instead of trying to place all symbols altogether an doing linear
+    search which is very time consuming, create a tree with one depth,
+    grouping similar symbols altogether.
+    Yet, sometimes a full search will be needed, so we have a special branch
+    on such group tree where other symbols are placed.
+    """
+    #: Escape only ASCII visible characters.
     escape_symbols = r"([\x21-\x29\x2b-\x2d\x3a-\x40\x5c\x60\x7b-\x7e])"
+    #: Special group for other nodes.
     leave_others = "others"
     # Tuples with regular expressions to be compiled and replacement data
         # Recover plus characters
         (re.compile(r"\xf7"), "+"),
     ]
+    #: Regex to check if the symbol name has a number on it.
     re_has_num = re.compile(r"\\d")
-    # Symbol name after escape_chars that are considered a devnode basename
+    #: Symbol name after escape_chars that are considered a devnode basename.
     re_symbol_name =  re.compile(r"(\w|\\[\.\-\:])+$")
-    # List of popular group names to be skipped to minimize regex group size
+    #: List of popular group names to be skipped to minimize regex group size
-    # Use AbiDebug.SUBGROUP_SIZE to detect those
+    #: Use AbiDebug.SUBGROUP_SIZE to detect those.
     skip_names = set(["devices", "hwmon"])
     def regex_append(self, what, new):
     def get_regexes(self, what):
         """
         Given an ABI devnode, return a list of all regular expressions that
-        may match it, based on the sub-groups created by regex_append()
+        may match it, based on the sub-groups created by regex_append().
         """
         re_list = []