libnvme: rename !accessors: member annotation to !access:

Rename the member-level annotation prefix from !accessors: to !access:
to decouple it from the !generate-accessors struct-level annotation.

Until now, the !accessors:<value> member annotation was consumed only
by the accessor generator, and its name reflected that — it read as a
natural companion to the struct-level !generate-accessors annotation.

That one-to-one relationship is about to change. An upcoming
!generate-python struct-level annotation will also need to read the
same member annotations, both to drive the generated SWIG layer and to
validate consistency between the C and Python sides. The annotation is
no longer the private concern of the accessor generator.

Keeping the name !accessors: would make that relationship confusing:

  - The visual similarity to !generate-accessors suggests the member
    annotation is owned by accessor generation, when in fact multiple
    generators will consume it.
  - Readers (and future contributors adding more generators) would
    reasonably — but wrongly — assume the annotation is accessor
    specific and only relevant when !generate-accessors is set.

Renaming to !access: breaks that false association. The new name also
reads more naturally as English:

  char *name;  // !access:readonly
  char *addr;  // !access:none

vs.

  char *name;  // !accessors:readonly
  char *addr;  // !accessors:none

This patch is a pure rename with no behavioural change:

  - generate-accessors.py: update has_annotation() lookups and the
    docstring examples
  - private.h: rename all 47 member annotations
  - generate-accessors.md: update every example, table row and note;
    re-pad the affected table rows to preserve column alignment

Generator output (accessors.h / accessors.c / accessors.ld) is byte
identical before and after this commit.

Signed-off-by: Martin Belanger <Martin.Belanger@dell.com>
Assisted-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: Martin Belanger

libnvme/src/nvme/private.h

@@ -202,20 +202,20 @@ struct libnvme_path {			// !generate-accessors
 
 	struct libnvme_stat stat[2];	/* gendisk I/O stat */
 	unsigned int curr_idx;		/* current index into the stat[] */
-	bool diffstat;			// !accessors:none
+	bool diffstat;			// !access:none
 
 	struct libnvme_ctrl *c;
 	struct libnvme_ns *n;
 
 	char *name;
 	char *sysfs_dir;
-	char *ana_state;		// !accessors:none
-	char *numa_nodes;		// !accessors:none
+	char *ana_state;		// !access:none
+	char *numa_nodes;		// !access:none
 	int grpid;
-	int queue_depth;		// !accessors:none
-	long multipath_failover_count;	// !accessors:none
-	long command_retry_count;	// !accessors:none
-	long command_error_count;	// !accessors:none
+	int queue_depth;		// !access:none
+	long multipath_failover_count;	// !access:none
+	long command_retry_count;	// !access:none
+	long command_error_count;	// !access:none
 };
 
 struct libnvme_ns_head {
@@ -236,12 +236,12 @@ struct libnvme_ns {			// !generate-accessors
 
 	struct libnvme_stat stat[2];	/* gendisk I/O stat */
 	unsigned int curr_idx;		/* current index into the stat[] */
-	bool diffstat;			// !accessors:none
+	bool diffstat;			// !access:none
 
 	struct libnvme_transport_handle *hdl;
 	__u32 nsid;
 	char *name;
-	char *generic_name;		// !accessors:none
+	char *generic_name;		// !access:none
 	char *sysfs_dir;
 
 	int lba_shift;
@@ -255,10 +255,10 @@ struct libnvme_ns {			// !generate-accessors
 	unsigned char uuid[NVME_UUID_LEN];
 	enum nvme_csi csi;
 
-	long command_retry_count;		// !accessors:none
-	long command_error_count;		// !accessors:none
-	long requeue_no_usable_path_count;	// !accessors:none
-	long fail_no_available_path_count;	// !accessors:none
+	long command_retry_count;		// !access:none
+	long command_error_count;		// !access:none
+	long requeue_no_usable_path_count;	// !access:none
+	long fail_no_available_path_count;	// !access:none
 };
 
 struct libnvme_ctrl {			// !generate-accessors
@@ -269,38 +269,38 @@ struct libnvme_ctrl {			// !generate-accessors
 
 	struct libnvme_global_ctx *ctx;
 	struct libnvme_transport_handle *hdl;
-	char *name;			// !accessors:readonly
-	char *sysfs_dir;		// !accessors:readonly
-	char *address;			// !accessors:none
-	char *firmware;			// !accessors:readonly
-	char *model;			// !accessors:readonly
-	char *state;			// !accessors:none
-	char *numa_node;	 	// !accessors:readonly
-	char *queue_count;		// !accessors:readonly
-	char *serial;			// !accessors:readonly
-	char *sqsize;			// !accessors:readonly
-	char *transport;		// !accessors:readonly
-	char *subsysnqn;		// !accessors:readonly
-	char *traddr;			// !accessors:readonly
-	char *trsvcid;			// !accessors:readonly
+	char *name;			// !access:readonly
+	char *sysfs_dir;		// !access:readonly
+	char *address;			// !access:none
+	char *firmware;			// !access:readonly
+	char *model;			// !access:readonly
+	char *state;			// !access:none
+	char *numa_node;	 	// !access:readonly
+	char *queue_count;		// !access:readonly
+	char *serial;			// !access:readonly
+	char *sqsize;			// !access:readonly
+	char *transport;		// !access:readonly
+	char *subsysnqn;		// !access:readonly
+	char *traddr;			// !access:readonly
+	char *trsvcid;			// !access:readonly
 	char *dhchap_host_key;
 	char *dhchap_ctrl_key;
 	char *keyring;
 	char *tls_key_identity;
 	char *tls_key;
-	char *cntrltype;		// !accessors:readonly
-	char *cntlid;			// !accessors:readonly
-	char *dctype;			// !accessors:readonly
-	char *phy_slot;			// !accessors:readonly
-	char *host_traddr;		// !accessors:readonly
-	char *host_iface;		// !accessors:readonly
+	char *cntrltype;		// !access:readonly
+	char *cntlid;			// !access:readonly
+	char *dctype;			// !access:readonly
+	char *phy_slot;			// !access:readonly
+	char *host_traddr;		// !access:readonly
+	char *host_iface;		// !access:readonly
 	bool discovery_ctrl;
 	bool unique_discovery_ctrl;
 	bool discovered;
 	bool persistent;
-	long command_error_count;	// !accessors:none
-	long reset_count;		// !accessors:none
-	long reconnect_count;		// !accessors:none
+	long command_error_count;	// !access:none
+	long reset_count;		// !access:none
+	long reconnect_count;		// !access:none
 	struct libnvme_fabrics_config cfg;
 };
 
@@ -310,27 +310,27 @@ struct libnvme_subsystem {		// !generate-accessors
 	struct list_head namespaces;
 	struct libnvme_host *h;
 
-	char *name;			// !accessors:readonly
-	char *sysfs_dir;		// !accessors:readonly
-	char *subsysnqn;		// !accessors:readonly
-	char *model;			// !accessors:readonly
-	char *serial;			// !accessors:readonly
-	char *firmware;			// !accessors:readonly
-	char *subsystype;		// !accessors:readonly
+	char *name;			// !access:readonly
+	char *sysfs_dir;		// !access:readonly
+	char *subsysnqn;		// !access:readonly
+	char *model;			// !access:readonly
+	char *serial;			// !access:readonly
+	char *firmware;			// !access:readonly
+	char *subsystype;		// !access:readonly
 	char *application;
-	char *iopolicy;			// !accessors:none
+	char *iopolicy;			// !access:none
 };
 
 struct libnvme_host {			// !generate-accessors
 	struct list_node entry;
 	struct list_head subsystems;
 	struct libnvme_global_ctx *ctx;
 
-	char *hostnqn;			// !accessors:readonly
-	char *hostid;			// !accessors:readonly
+	char *hostnqn;			// !access:readonly
+	char *hostid;			// !access:readonly
 	char *dhchap_host_key;
 	char *hostsymname;
-	bool pdc_enabled;		// !accessors:none
+	bool pdc_enabled;		// !access:none
 	bool pdc_enabled_valid; /* set if pdc_enabled doesn't have an undefined
 				 * value */
 };

libnvme/tools/generator/generate-accessors.md

@@ -59,8 +59,8 @@ Place the annotation on a member's declaration line to suppress accessor generat
 ```c
 struct nvme_ctrl { // !generate-accessors
     char *name;
-    char *state;      // !accessors:none
-    char *subsysnqn;  // !accessors:none
+    char *state;      // !access:none
+    char *subsysnqn;  // !access:none
 };
 ```
 
@@ -71,8 +71,8 @@ Place the annotation on a member's declaration line to generate only a getter (n
 ```c
 struct nvme_ctrl { // !generate-accessors
     char *name;
-    char *firmware;   // !accessors:readonly
-    char *model;      // !accessors:readonly
+    char *firmware;   // !access:readonly
+    char *model;      // !access:readonly
 };
 ```
 
@@ -85,7 +85,7 @@ Place the annotation on a member's declaration line to generate only a setter (n
 ```c
 struct nvme_ctrl { // !generate-accessors:readonly
     char *name;       /* getter only (struct default) */
-    char *token;      // !accessors:writeonly    /* setter only override */
+    char *token;      // !access:writeonly    /* setter only override */
 };
 ```
 
@@ -96,8 +96,8 @@ Place the annotation on a member's declaration line to generate both a getter an
 ```c
 struct nvme_ctrl { // !generate-accessors:none
     char *name;       /* no accessors (struct default) */
-    char *model;      // !accessors:readwrite    /* both getter and setter */
-    char *firmware;   // !accessors:readonly     /* getter only */
+    char *model;      // !access:readwrite    /* both getter and setter */
+    char *firmware;   // !access:readonly     /* getter only */
 };
 ```
 
@@ -140,7 +140,7 @@ struct nvme_ctrl { // !generate-lifecycle
 };
 ```
 
-This annotation has no effect on accessor generation. Combine with `// !accessors:none` if both should be suppressed.
+This annotation has no effect on accessor generation. Combine with `// !access:none` if both should be suppressed.
 
 ### Member defaults — `default:VALUE`
 
@@ -168,10 +168,10 @@ The value is emitted verbatim, so any valid C expression — integer literals, m
 | `// !generate-accessors:readonly`        | struct brace | Include struct, default: getter only                      |
 | `// !generate-accessors:writeonly`       | struct brace | Include struct, default: setter only                      |
 | `// !generate-lifecycle`                 | struct brace | Generate constructor + destructor                         |
-| `// !accessors:none`                     | member line  | Skip this member entirely (accessors only)                |
-| `// !accessors:readonly`                 | member line  | Generate getter only                                      |
-| `// !accessors:writeonly`                | member line  | Generate setter only                                      |
-| `// !accessors:readwrite`                | member line  | Generate getter and setter                                |
+| `// !access:none`                        | member line  | Skip this member entirely (accessors only)                |
+| `// !access:readonly`                    | member line  | Generate getter only                                      |
+| `// !access:writeonly`                   | member line  | Generate setter only                                      |
+| `// !access:readwrite`                   | member line  | Generate getter and setter                                |
 | `// !lifecycle:none`                     | member line  | Exclude member from destructor free logic                 |
 | `// !default:VALUE`                      | member line  | Set field to VALUE in `init_defaults()`                   |
 | `const` qualifier on member              | member type  | Suppress setter; suppress free in destructor              |
@@ -187,8 +187,8 @@ struct person { // !generate-accessors
     char *name;
     int age;
     const char *id;       /* const → getter only, no annotation needed */
-    char *secret;         // !accessors:none
-    char *role;           // !accessors:readonly
+    char *secret;         // !access:none
+    char *role;           // !access:readonly
 };
 
 struct car { // !generate-accessors
@@ -319,7 +319,7 @@ const char *car_get_vin(const struct car *p);
 #endif /* _ACCESSORS_H_ */
 ```
 
-> **Note:** The `secret` member is absent because of `// !accessors:none` — excluded members leave no trace in the output. The `role` member has only a getter because of `// !accessors:readonly`. The `id` and `vin` members have only getters because they are declared `const`.
+> **Note:** The `secret` member is absent because of `// !access:none` — excluded members leave no trace in the output. The `role` member has only a getter because of `// !access:readonly`. The `id` and `vin` members have only getters because they are declared `const`.
 
 ### Generated `accessors.c`
 
@@ -422,7 +422,7 @@ LIBNVME_ACCESSORS_3 {
 };
 ```
 
-> **Note:** Only symbols for members that have accessors generated appear in the linker script. The `secret` member (excluded via `// !accessors:none`) and the write-only `token` example would have no getter entry. The version node name `LIBNVME_ACCESSORS_3` is hardcoded in the generator.
+> **Note:** Only symbols for members that have accessors generated appear in the linker script. The `secret` member (excluded via `// !access:none`) and the write-only `token` example would have no getter entry. The version node name `LIBNVME_ACCESSORS_3` is hardcoded in the generator.
 
 ------
 
@@ -437,8 +437,8 @@ struct person { // !generate-accessors !generate-lifecycle
     char *name;
     int age;
     const char *id;       /* const → getter only; NOT freed by destructor */
-    char *secret;         // !accessors:none
-    char *role;           // !accessors:readonly
+    char *secret;         // !access:none
+    char *role;           // !access:readonly
 };
 ```
 
@@ -491,7 +491,7 @@ __public void person_free(struct person *p)
 
 > **Notes:**
 > - `id` is `const char *` — the destructor never frees `const` members.
-> - `secret` is `// !accessors:none` but is still freed — `lifecycle:none` is the annotation to suppress a free.
+> - `secret` is `// !access:none` but is still freed — `lifecycle:none` is the annotation to suppress a free.
 > - `age` is `int` — only `char *` and `char **` members are freed.
 
 ### Additional entries in `accessors.ld`
@@ -611,10 +611,10 @@ __public void conn_opts_free(struct conn_opts *p)
 2. **String arrays** (`char **`) — setters deep-copy NULL-terminated arrays (each element and the container).
 3. **Fixed char arrays** (`char foo[N]`) — setters use `snprintf`, always NUL-terminated.
 4. **`const` members** — only a getter is generated, no setter (applies regardless of any annotation). `const char *` members are also skipped by the destructor.
-5. **`// !accessors:readonly`** — same effect as `const`: getter only.
-6. **`// !accessors:writeonly`** — setter only; getter is suppressed.
-7. **`// !accessors:readwrite`** — both getter and setter; overrides a restrictive struct-level default.
-8. **`// !accessors:none`** — member is completely ignored by the accessor generator. The destructor still frees it unless `// !lifecycle:none` is also present.
+5. **`// !access:readonly`** — same effect as `const`: getter only.
+6. **`// !access:writeonly`** — setter only; getter is suppressed.
+7. **`// !access:readwrite`** — both getter and setter; overrides a restrictive struct-level default.
+8. **`// !access:none`** — member is completely ignored by the accessor generator. The destructor still frees it unless `// !lifecycle:none` is also present.
 9. **Struct-level mode** — the qualifier on `generate-accessors` sets the default for every member in the struct; per-member annotations override the struct default.
 10. **`// !generate-lifecycle`** — generates `foo_new()` (constructor) and `foo_free()` (destructor). Can appear on the same line as `generate-accessors`. A struct needs only one of the two annotations.
 11. **`// !lifecycle:none`** — excludes a member from the destructor's free logic. Use this when the struct does not own the pointed-to memory.

libnvme/tools/generator/generate-accessors.py

@@ -55,20 +55,20 @@
 strdup) since they are assumed to point to externally owned storage.
 
 Member exclusion — annotate the member declaration line:
-  char *model; // !accessors:none
+  char *model; // !access:none
 
 Read-only members (getter only, setter suppressed):
   - Members declared with the 'const' qualifier, or
   - Annotate the member declaration line:
-      char *state; // !accessors:readonly
+      char *state; // !access:readonly
 
 Write-only members (setter only, getter suppressed):
   - Annotate the member declaration line:
-      char *state; // !accessors:writeonly
+      char *state; // !access:writeonly
 
 Both getter and setter (override a restrictive struct-level default):
   - Annotate the member declaration line:
-      char *state; // !accessors:readwrite
+      char *state; // !access:readwrite
 
 Example usage:
   ./generate-accessors.py private.h
@@ -301,14 +301,14 @@ def parse_members(struct_name, raw_body, struct_mode, verbose):
         # ----------------------------------------------------------------
         # Annotation checks on the raw line — BEFORE stripping comments.
         # ----------------------------------------------------------------
-        if has_annotation(raw_line, 'accessors:none'):
+        if has_annotation(raw_line, 'access:none'):
             continue
 
-        if has_annotation(raw_line, 'accessors:readwrite'):
+        if has_annotation(raw_line, 'access:readwrite'):
             member_mode = 'both'
-        elif has_annotation(raw_line, 'accessors:readonly'):
+        elif has_annotation(raw_line, 'access:readonly'):
             member_mode = 'readonly'
-        elif has_annotation(raw_line, 'accessors:writeonly'):
+        elif has_annotation(raw_line, 'access:writeonly'):
             member_mode = 'writeonly'
         else:
             member_mode = struct_mode