varlink: add IDL comments to basic Varlink service interface

(cherry picked from commit 23860b49753189e2aaf2e0c8d7b50fe6b1e5a065)
(cherry picked from commit b365d34a0cfd65a6a0f10bbc69751a33d0cb9f40)

diff --git a/src/libsystemd/sd-varlink/varlink-org.varlink.service.c b/src/libsystemd/sd-varlink/varlink-org.varlink.service.c
index 7b7121eb417a2b40704050894f7ce526e0a92bff..d91670899af3aea23b5865b34918908f88bad316 100644 (file)
--- a/src/libsystemd/sd-varlink/varlink-org.varlink.service.c
+++ b/src/libsystemd/sd-varlink/varlink-org.varlink.service.c
@@ -4,31 +4,42 @@
 
 static SD_VARLINK_DEFINE_METHOD(
                 GetInfo,
+                SD_VARLINK_FIELD_COMMENT("String identifying the vendor of this service"),
                 SD_VARLINK_DEFINE_OUTPUT(vendor, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("String identifying the product implementing this service"),
                 SD_VARLINK_DEFINE_OUTPUT(product, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("Version string of this product"),
                 SD_VARLINK_DEFINE_OUTPUT(version, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("Web URL pointing to additional information about this service"),
                 SD_VARLINK_DEFINE_OUTPUT(url, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("List of interfaces implemented by this service"),
                 SD_VARLINK_DEFINE_OUTPUT(interfaces, SD_VARLINK_STRING, SD_VARLINK_ARRAY));
 
 static SD_VARLINK_DEFINE_METHOD(
                 GetInterfaceDescription,
+                SD_VARLINK_FIELD_COMMENT("Name of interface to query interface description of"),
                 SD_VARLINK_DEFINE_INPUT(interface, SD_VARLINK_STRING, 0),
+                SD_VARLINK_FIELD_COMMENT("Interface description in Varlink IDL format"),
                 SD_VARLINK_DEFINE_OUTPUT(description, SD_VARLINK_STRING, 0));
 
 static SD_VARLINK_DEFINE_ERROR(
                 InterfaceNotFound,
+                SD_VARLINK_FIELD_COMMENT("Name of interface that was called but does not exist"),
                 SD_VARLINK_DEFINE_FIELD(interface, SD_VARLINK_STRING, 0));
 
 static SD_VARLINK_DEFINE_ERROR(
                 MethodNotFound,
+                SD_VARLINK_FIELD_COMMENT("Name of method that was called but does not exist"),
                 SD_VARLINK_DEFINE_FIELD(method, SD_VARLINK_STRING, 0));
 
 static SD_VARLINK_DEFINE_ERROR(
                 MethodNotImplemented,
+                SD_VARLINK_FIELD_COMMENT("Name of method that was called but is not implemented."),
                 SD_VARLINK_DEFINE_FIELD(method, SD_VARLINK_STRING, 0));
 
 static SD_VARLINK_DEFINE_ERROR(
                 InvalidParameter,
+                SD_VARLINK_FIELD_COMMENT("Name of the invalid parameter"),
                 SD_VARLINK_DEFINE_FIELD(parameter, SD_VARLINK_STRING, 0));
 
 static SD_VARLINK_DEFINE_ERROR(PermissionDenied);
@@ -39,11 +50,20 @@ static SD_VARLINK_DEFINE_ERROR(ExpectedMore);
 SD_VARLINK_DEFINE_INTERFACE(
                 org_varlink_service,
                 "org.varlink.service",
+                SD_VARLINK_INTERFACE_COMMENT("General Varlink service interface"),
+                SD_VARLINK_SYMBOL_COMMENT("Get service meta information"),
                 &vl_method_GetInfo,
+                SD_VARLINK_SYMBOL_COMMENT("Get description of an implemented interface in Varlink IDL format"),
                 &vl_method_GetInterfaceDescription,
+                SD_VARLINK_SYMBOL_COMMENT("Error returned if a method is called on an unknown interface"),
                 &vl_error_InterfaceNotFound,
+                SD_VARLINK_SYMBOL_COMMENT("Error returned if an unknown method is called on an known interface"),
                 &vl_error_MethodNotFound,
+                SD_VARLINK_SYMBOL_COMMENT("Error returned if an method is called that is known but not implemented"),
                 &vl_error_MethodNotImplemented,
+                SD_VARLINK_SYMBOL_COMMENT("Error returned if a method is called with an invalid parameter"),
                 &vl_error_InvalidParameter,
+                SD_VARLINK_SYMBOL_COMMENT("General permission error"),
                 &vl_error_PermissionDenied,
+                SD_VARLINK_SYMBOL_COMMENT("A method was called with the 'more' flag off, but it may only be called with the flag turned on"),
                 &vl_error_ExpectedMore);