trustee: document rights and trustee helper functions

Add function-level comments to the Trustee/Rights helper routines in trustee.c.

Document option parsing, rights word parsing and formatting, bindery object
lookup, and trustee-specific directory handling. This clarifies the intended
split between generic helpers in tools.c and Trustee/Rights-specific behavior
in trustee.c.

No behavior change.

trustee.c

@@ -31,9 +31,20 @@
 #define S_IFDIR 0040000
 #endif
 
-
-
-
+/*
+ * trustee_is_subdirs_option
+ *
+ * Purpose:
+ *   Recognizes the GRANT/REMOVE/REVOKE option variants that request
+ *   recursive processing of subdirectories.
+ *
+ * Parameters:
+ *   s - command-line token to test.
+ *
+ * Returns:
+ *   Non-zero when the token is a /SUBDIRS, /SUBDIRECTORIES or /S option,
+ *   otherwise zero.
+ */
 int trustee_is_subdirs_option(char *s)
 {
   if (!s) return(0);
@@ -42,6 +53,19 @@ int trustee_is_subdirs_option(char *s)
          tool_strsame(s, "/S") || tool_strsame(s, "-S"));
 }
 
+/*
+ * trustee_is_files_option
+ *
+ * Purpose:
+ *   Recognizes the option variants that request file entries in addition to
+ *   directories for trustee operations.
+ *
+ * Parameters:
+ *   s - command-line token to test.
+ *
+ * Returns:
+ *   Non-zero for /FILES or /F variants, otherwise zero.
+ */
 int trustee_is_files_option(char *s)
 {
   if (!s) return(0);
@@ -49,6 +73,27 @@ int trustee_is_files_option(char *s)
          tool_strsame(s, "/F") || tool_strsame(s, "-F"));
 }
 
+/*
+ * trustee_parse_right_word
+ *
+ * Purpose:
+ *   Converts one Novell-style trustee right word into the corresponding
+ *   386 trustee rights mask bits.
+ *
+ * Parameters:
+ *   s      - right word or one-letter abbreviation, such as READ, R, CREATE,
+ *            C, SUPERVISOR or S.
+ *   rights - in/out accumulated rights mask updated on success.
+ *
+ * Returns:
+ *   0 when the word was recognized, -1 for an unknown right word.
+ *
+ * Notes:
+ *   The command parsers call this repeatedly so individual right words can be
+ *   accumulated into one mask. The historical NONE handling is preserved here
+ *   and should only be changed together with the GRANT/REVOKE compatibility
+ *   tests.
+ */
 int trustee_parse_right_word(char *s, uint16 *rights)
 {
   if (tool_strsame(s, "ALL")) {
@@ -107,6 +152,21 @@ int trustee_parse_right_word(char *s, uint16 *rights)
   return(-1);
 }
 
+/*
+ * trustee_rights_bracket
+ *
+ * Purpose:
+ *   Formats a 386 trustee rights mask as the Novell-style eight-character
+ *   bracket body used by GRANT, REMOVE and REVOKE output.
+ *
+ * Parameters:
+ *   rights - trustee rights mask.
+ *   out    - caller-supplied buffer receiving an 8-character string plus NUL.
+ *
+ * Notes:
+ *   Missing rights are rendered as spaces, not dashes. Keep this formatting
+ *   stable because the command output is compared against Novell tools.
+ */
 void trustee_rights_bracket(uint16 rights, char *out)
 {
   out[0] = (rights & TRUSTEE_RIGHT_SUPER)  ? 'S' : ' ';
@@ -120,6 +180,29 @@ void trustee_rights_bracket(uint16 rights, char *out)
   out[8] = '\0';
 }
 
+/*
+ * trustee_lookup_object
+ *
+ * Purpose:
+ *   Resolves a trustee name to a bindery object ID for GRANT/REMOVE/REVOKE
+ *   style operations.
+ *
+ * Parameters:
+ *   name          - bindery object name supplied on the command line.
+ *   objtype       - in/out bindery object type. When objtype_given is false,
+ *                   receives the matching USER or GROUP type.
+ *   objtype_given - non-zero when the caller already selected a concrete
+ *                   bindery object type.
+ *
+ * Returns:
+ *   Non-zero bindery object ID on success, or zero when no matching object was
+ *   found.
+ *
+ * NCP:
+ *   Uses ncp17_35_get_bindery_object_id(). If no explicit type is supplied,
+ *   USER is tried first and GROUP second, matching the common Novell command
+ *   behavior.
+ */
 uint32 trustee_lookup_object(char *name, uint16 *objtype, int objtype_given)
 {
   uint8 namebuf[48];
@@ -142,6 +225,25 @@ uint32 trustee_lookup_object(char *name, uint16 *objtype, int objtype_given)
   return(object_id);
 }
 
+/*
+ * trustee_path_is_dir
+ *
+ * Purpose:
+ *   Tests whether a path should be treated as a directory by the trustee
+ *   commands.
+ *
+ * Parameters:
+ *   path - DOS/NetWare path to test.
+ *
+ * Returns:
+ *   Non-zero when the path is empty/current-directory syntax or stat() reports
+ *   a directory, otherwise zero.
+ *
+ * Notes:
+ *   This remains in trustee.c because the empty/current-directory handling is
+ *   part of the GRANT/REMOVE/REVOKE trustee command semantics rather than a
+ *   completely generic path predicate.
+ */
 int trustee_path_is_dir(char *path)
 {
   struct stat st;