Internal documentation: clarify the (different) purpose of the grant and permission crawlers (#2592)

## Changes

Following some #2074-related discussions yesterday, this PR adds some
internal documentation to clarify the intended (different) purposes of
the grants and permissions crawlers.

Author: asnare

src/databricks/labs/ucx/assessment/workflows.py

@@ -25,11 +25,10 @@ def setup_tacl(self, ctx: RuntimeContext):
 
     @job_task(depends_on=[crawl_tables, setup_tacl], job_cluster="tacl")
     def crawl_grants(self, ctx: RuntimeContext):
-        """Scans the previously created Delta table named `$inventory_database.tables` and issues a `SHOW GRANTS`
-        statement for every object to retrieve the permissions it has assigned to it. The permissions include information
-        such as the _principal_, _action type_, and the _table_ it applies to. This is persisted in the Delta table
-        `$inventory_database.grants`. Other, migration related jobs use this inventory table to convert the legacy Table
-        ACLs to Unity Catalog  permissions.
+        """Scans all securable objects for permissions that have been assigned: this include database-level permissions,
+        as well permissions directly configured on objects in the (already gathered) table and UDF inventories. The
+        captured information is stored in the `$inventory_database.grants` inventory table for further use during the
+        migration of legacy ACLs to Unity Catalog permissions.
 
         Note: This job runs on a separate cluster (named `tacl`) as it requires the proper configuration to have the Table
         ACLs enabled and available for retrieval."""

src/databricks/labs/ucx/hive_metastore/grants.py

@@ -196,6 +196,8 @@ def uc_grant_sql(self, object_type: str | None = None, object_key: str | None =
 
 
 class GrantsCrawler(CrawlerBase[Grant]):
+    """Crawler that captures access controls that relate to data and other securable objects."""
+
     def __init__(self, tc: TablesCrawler, udf: UdfsCrawler, include_databases: list[str] | None = None):
         assert tc._backend == udf._backend
         assert tc._catalog == udf._catalog

src/databricks/labs/ucx/workspace_access/manager.py

@@ -14,6 +14,13 @@
 
 
 class PermissionManager(CrawlerBase[Permissions]):
+    """Crawler that captures permissions, intended for configuration-related (non-data) objects.
+
+    The set of objects types captured depends on the (sub)-crawlers supplied to the initializer, but is intended to
+    cover configuration-related (non-data) objects such as workspace configuration, dashboards, secrets, SCIM
+    entitlements, etc.
+    """
+
     ERRORS_TO_IGNORE = ["FEATURE_DISABLED"]
 
     def __init__(self, backend: SqlBackend, inventory_database: str, crawlers: list[AclSupport]):