varlink: comment that "more" flag IDL comment is API

External tools that use the systemd varlink ecosystem require
to know if a specific varlink method supports/requires the
"more" flag from the IDL. This is tracked upstream in
https://github.com/varlink/varlink.github.io/issues/26

As an intermediate step systemd adds the (very nice) comments
```
 # [Requires 'more' flag]
or
 # [Supports 'more' flag]
```
to the various methods.

This commit extends the comment around the code that adds the
comment to clarify that this should be considered API and that
the comment should not be changed as external tools (like e.g.
the varlink-http-bridge) rely on it.

diff --git a/src/libsystemd/sd-varlink/sd-varlink-idl.c b/src/libsystemd/sd-varlink/sd-varlink-idl.c
index 144450b702d26af6eea538bc627723d6f4a1c35f..22b6026a01f149f66141d13edc91c7edb03055b4 100644 (file)
--- a/src/libsystemd/sd-varlink/sd-varlink-idl.c
+++ b/src/libsystemd/sd-varlink/sd-varlink-idl.c
@@ -387,7 +387,10 @@ static int varlink_idl_format_symbol(
 
                 /* Sooner or later we want to export this in a proper IDL language construct, see
                  * https://github.com/varlink/varlink.github.io/issues/26 – but for now export this as a
-                 * comment. */
+                 * comment.
+                 *
+                 * Until this is resolved upsteam, consider this comment part of the API (i.e. don't change
+                 * only extend). It is used by tools like varlink-http-bridge. */
                 if ((symbol->symbol_flags & (SD_VARLINK_REQUIRES_MORE|SD_VARLINK_SUPPORTS_MORE)) != 0) {
                         fputs(colors[COLOR_COMMENT], f);
                         if (FLAGS_SET(symbol->symbol_flags, SD_VARLINK_REQUIRES_MORE))