docs: clarify when to use varlink enum types vs plain strings

Add guidance on when a field should use a proper varlink enum type
versus remaining a plain string: user-controlled/API fields should be
enums, engine-internal state fields may stay as strings.

Co-developed-by: Claude Opus 4.6 <noreply@anthropic.com>

diff --git a/docs/VARLINK.md b/docs/VARLINK.md
index 844c4ca516bd8b92129f70758f1207a71b086687..65f1950800b590c2429efdc0710774e5c3ef8afd 100644 (file)
--- a/docs/VARLINK.md
+++ b/docs/VARLINK.md
@@ -63,11 +63,22 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   * `JSON_DISPATCH_ENUM_DEFINE` - creates a `json_dispatch_*` function that
     accepts both the original and the underscorified enum value as valid input.
 
+  For example, a `LogTarget` field outputs `"journal_or_kmsg"` (underscore
+  form), but on input both `"journal_or_kmsg"` and `"journal-or-kmsg"` are
+  accepted. This is handled automatically by `JSON_DISPATCH_ENUM_DEFINE`:
+  it first tries the value as-is via `_from_string()`, and if that fails,
+  replaces underscores with dashes and retries.
+
 - An internal enum may be exposed as a simple string field instead of a Varlink
   enum type when the field is output-only and never provided or controlled by
   the user. However, such fields should avoid using dashes to prevent breaking
   changes if they are later converted into enums (see below).
 
+  For example, in `io.systemd.Unit`, configuration settings that users select
+  in unit files (e.g. `ProtectSystem`, `ExecInputType`) should be proper varlink
+  enum types. Runtime state fields that only the engine determines (e.g.
+  `ActiveState`, `SubState`) may remain plain strings.
+
 - A varlink string field that has a finite set of possible values may later be
   converted into an enum without introducing a breaking change. This allows the
   interface to evolve from loosely defined string values to a more explicit and