man: drop documentation of internal lookup flags

This removes documentation of SD_RESOLVED_REQUIRE_PRIMARY and
SD_RESOLVED_CLAMP_TTL, which are internal flags, and not usable from
outside of resolved. They are refused by D-Bus APIs, for a reason.

Various other fixes/clean-ups of the relevant docs (including reordering
of the flags docs by "grouping" rather than bit values).

Fixes: #26619

1 files changed, 32 insertions, 33 deletions

diff --git a/man/org.freedesktop.resolve1.xml b/man/org.freedesktop.resolve1.xml
index 54f0a18418..a2b4490fc7 100644
--- a/man/org.freedesktop.resolve1.xml
+++ b/man/org.freedesktop.resolve1.xml
@@ -439,32 +439,36 @@ node /org/freedesktop/resolve1 {
         <para>The four methods above accept and return a 64-bit flags value. In most cases passing 0 is sufficient
         and recommended. However, the following flags are defined to alter the look-up:</para>
 
-        <programlisting>
+        <programlisting>/* Input+Output: Protocol/scope */
 #define SD_RESOLVED_DNS               (UINT64_C(1) &lt;&lt;  0)
 #define SD_RESOLVED_LLMNR_IPV4        (UINT64_C(1) &lt;&lt;  1)
 #define SD_RESOLVED_LLMNR_IPV6        (UINT64_C(1) &lt;&lt;  2)
 #define SD_RESOLVED_MDNS_IPV4         (UINT64_C(1) &lt;&lt;  3)
 #define SD_RESOLVED_MDNS_IPV6         (UINT64_C(1) &lt;&lt;  4)
+
+/* Input: Restrictions */
 #define SD_RESOLVED_NO_CNAME          (UINT64_C(1) &lt;&lt;  5)
 #define SD_RESOLVED_NO_TXT            (UINT64_C(1) &lt;&lt;  6)
 #define SD_RESOLVED_NO_ADDRESS        (UINT64_C(1) &lt;&lt;  7)
 #define SD_RESOLVED_NO_SEARCH         (UINT64_C(1) &lt;&lt;  8)
-#define SD_RESOLVED_AUTHENTICATED     (UINT64_C(1) &lt;&lt;  9)
 #define SD_RESOLVED_NO_VALIDATE       (UINT64_C(1) &lt;&lt; 10)
 #define SD_RESOLVED_NO_SYNTHESIZE     (UINT64_C(1) &lt;&lt; 11)
 #define SD_RESOLVED_NO_CACHE          (UINT64_C(1) &lt;&lt; 12)
 #define SD_RESOLVED_NO_ZONE           (UINT64_C(1) &lt;&lt; 13)
 #define SD_RESOLVED_NO_TRUST_ANCHOR   (UINT64_C(1) &lt;&lt; 14)
 #define SD_RESOLVED_NO_NETWORK        (UINT64_C(1) &lt;&lt; 15)
-#define SD_RESOLVED_REQUIRE_PRIMARY   (UINT64_C(1) &lt;&lt; 16)
-#define SD_RESOLVED_CLAMP_TTL         (UINT64_C(1) &lt;&lt; 17)
+
+/* Output: Security */
+#define SD_RESOLVED_AUTHENTICATED     (UINT64_C(1) &lt;&lt;  9)
 #define SD_RESOLVED_CONFIDENTIAL      (UINT64_C(1) &lt;&lt; 18)
+
+/* Output: Origin */
 #define SD_RESOLVED_SYNTHETIC         (UINT64_C(1) &lt;&lt; 19)
 #define SD_RESOLVED_FROM_CACHE        (UINT64_C(1) &lt;&lt; 20)
 #define SD_RESOLVED_FROM_ZONE         (UINT64_C(1) &lt;&lt; 21)
 #define SD_RESOLVED_FROM_TRUST_ANCHOR (UINT64_C(1) &lt;&lt; 22)
 #define SD_RESOLVED_FROM_NETWORK      (UINT64_C(1) &lt;&lt; 23)
-        </programlisting>
+</programlisting>
 
         <para>On input, the first five flags control the protocols to use for the look-up. They refer to
         classic unicast DNS, LLMNR via IPv4/UDP and IPv6/UDP respectively, as well as MulticastDNS via
@@ -476,8 +480,8 @@ node /org/freedesktop/resolve1 {
         address lookup domains). It will route neither of these to Unicast DNS servers. Also, it will do
         LLMNR and Multicast DNS only on interfaces suitable for multicast.</para>
 
-        <para>On output, these five flags indicate which protocol was used to execute the operation, and hence
-        where the data was found.</para>
+        <para>On output, these five flags indicate which protocol was used to execute the operation, and
+        hence where the data was found.</para>
 
         <para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
         earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
@@ -496,8 +500,19 @@ node /org/freedesktop/resolve1 {
         <para>The NO_SEARCH flag turns off the search domain logic. It is only defined for input in
         <function>ResolveHostname()</function>. When specified, single-label hostnames are not qualified
         using defined search domains, if any are configured. Note that <function>ResolveRecord()</function>
-        will never qualify single-label domain names using search domains. Also note that
-        multi-label hostnames are never subject to search list expansion.</para>
+        will never qualify single-label domain names using search domains. Also note that multi-label
+        hostnames are never subject to search list expansion.</para>
+
+        <para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be
+        used.</para>
+
+        <para>The next four flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables
+        synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in
+        <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE
+        disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR
+        disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be
+        provided without using the network, i.e. either from local sources or the cache.</para>
 
         <para>The AUTHENTICATED bit is defined only in the output flags of the four functions. If set, the
         returned data has been fully authenticated. Specifically, this bit is set for all DNSSEC-protected
@@ -510,31 +525,15 @@ node /org/freedesktop/resolve1 {
         trusted, or where there is proof that the data is "rightfully" unauthenticated (which includes cases
         where the underlying protocol or server does not support authenticating data).</para>
 
-        <para>NO_VALIDATE can be set to disable validation via DNSSEC even if it would normally be used.
-        </para>
-
-        <para>The next four flags allow disabling certain sources during resolution. NO_SYNTHESIZE disables
-        synthetic records, e.g. the local host name, see section SYNTHETIC RECORDS in
-        <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-        for more information. NO_CACHE disables the use of the cache of previously resolved records. NO_ZONE
-        disables answers using locally registered public LLMNR/mDNS resource records. NO_TRUST_ANCHOR
-        disables answers using locally configured trust anchors. NO_NETWORK requires all answers to be
-        provided without using the network, i.e. either from local sources or the cache.</para>
-
-        <para>With REQUIRE_PRIMARY the request must be answered from a "primary" answer, i.e. not from
-        resource records acquired as a side-effect of a previous transaction.</para>
-
-        <para>With CLAMP_TTL, if reply is answered from cache, the TTLs will be adjusted by age of cache
-        entry.</para>
+        <para>CONFIDENTIAL means the query was resolved via encrypted channels or never left this
+        system.</para>
 
-        <para>The next six bits flags are used in output and provide information about the source of the answer.
-        CONFIDENTIAL means the query was resolved via encrypted channels or never left this system.
-        FROM_SYNTHETIC means the query was (at least partially) synthesized.
-        FROM_CACHE means the query was answered (at least partially) using the cache.
-        FROM_ZONE means the query was answered (at least partially) using LLMNR/mDNS.
-        FROM_TRUST_ANCHOR means the query was answered (at least partially) using local trust anchors.
-        FROM_NETWORK means the query was answered (at least partially) using the network.
-        </para>
+        <para>The next five bits flags are used in output and provide information about the origin of the
+        answer. FROM_SYNTHETIC means the query was (at least partially) synthesized locally. FROM_CACHE means
+        the query was answered (at least partially) using the cache. FROM_ZONE means the query was answered
+        (at least partially) based on public, locally registered records. FROM_TRUST_ANCHOR means the query
+        was answered (at least partially) using local trust anchors. FROM_NETWORK means the query was
+        answered (at least partially) using the network.</para>
       </refsect3>
     </refsect2>