From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Wed, 19 Mar 2025 19:32:20 +0000 (+0000)
Subject: config derive: Improve docs
X-Git-Tag: debian/1.3.1~10^2~5
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=commitdiff_plain;h=9fc63d79980c9d2e17a507d7290b9746e139896a;p=hippotat.git

config derive: Improve docs

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/src/config_derive.rs b/src/config_derive.rs
index a8203f3..1f39d45 100644
--- a/src/config_derive.rs
+++ b/src/config_derive.rs
@@ -27,12 +27,38 @@ define_derive_deftly! {
   /// sections to look in.  But it is also used by general validation,
   /// unconditionally, to reject settings in the wrong section.
   ///
-  /// Atrributes:
+  /// # Atrributes `#[deftly(ATTR)]`
   ///
-  ///  * `limited`, `server`, `client`: cooked sets of settings;
-  ///    default `SKL` is `PerClient` except for `limited`
-  ///  * `global` and `per_client`: set the SKL.
-  ///  * `special(method, SKL)`
+  /// ## Overriding attributes (these take precedence)
+  ///
+  ///  * `skl = EXOR`: Set the SKL to `EXPR`.
+  ///  * `special`: use `ResolveContext::special_FIELDNAME`
+  ///
+  /// ## Other attributes
+  ///
+  ///  | attribute    | SKL      | `ResolveContext` | `I.C.Global` | notes |
+  ///  |--------------|-------------|------------------|-|-|
+  ///  | `global`     | `Global`    |             | global | |
+  ///  | `per_client` | `PerClient` |             | | |
+  ///  | `client`     | `PerClient` | `client`    | | |
+  ///  | `limited`    | `Limited`   | `limited`   | | |
+  ///  | `computed`:  | `None`      | `computed`  | | |
+  ///  | `server`     |             | `server`    | | usu. add `per_client`/`global` |
+  ///  | _default otherwise unspecified_ | _error_ | `ordinary` | not global |
+  ///
+  /// (Blank cells indicate that the attribute doesn't affect that output.)
+  ///
+  /// ## Resulting information for each field
+  ///
+  ///  * SKL of type `SectionKindList`, ends in up in `FIELDS`.
+  ///    Either `skl`, or exactly one of the SKL-setting attributes,
+  ///    must be provided.
+  ///
+  ///  * How to resolve it: which method on `ResolveContext` to call.
+  ///    Defaults to `ResolveContext::ordinary`.
+  ///
+  ///  * Whether to include the field in `InstanceConfigGlobal`.
+  ///    (`global`).
   ///
   /// Generated code
   ///