inventory: Add roles.<name>.description option and a warning if it is not set

lib/modules/inventory/distributed-service/inventory-adapter.nix

@@ -140,6 +140,12 @@
               imports = [
                 # Import the resolved module.
                 # i.e. clan.modules.admin
+                {
+                  options.module = lib.mkOption {
+                    type = lib.types.raw;
+                    default = (builtins.head instances).instance.module;
+                  };
+                }
                 (builtins.head instances).instance.resolvedModule
               ] # Include all the instances that correlate to the resolved module
               ++ (builtins.map (v: {

lib/modules/inventory/distributed-service/service-module.nix

@@ -381,6 +381,13 @@ in
                 roleName = name;
               in
               {
+                options.description = mkOption {
+                  type = lib.types.nullOr types.str;
+                  description = "A short description of the role '${name}', explaining it's effect on the supplied machine.";
+                  example = "Connects the supplied machine as a '${name}' to the 'example' service.";
+                  default = null;
+                };
+
                 options.interface = mkOption {
                   description = ''
                     Abstract interface of the role.
@@ -959,8 +966,21 @@ in
               (
                 let
                   failedAssertions = (lib.filterAttrs (_: v: !v.assertion) config.result.assertions);
+                  formatModule =
+                    if config.module.input != null then
+                      "${config.module.input}/${config.module.name}"
+                    else
+                      "<clan-core>/${config.module.name}";
+                  warningsWithNull = lib.mapAttrsToList (
+                    roleName: roleConfig:
+                    if (roleConfig.description == null) then
+                      "Missing description for role '${roleName}' of clanService '${formatModule}'"
+                    else
+                      null
+                  ) config.roles;
                 in
                 {
+                  warnings = (lib.filter (v: v != null) warningsWithNull);
                   assertions = lib.attrValues failedAssertions;
                 }
               )

lib/modules/inventoryClass/service-list-from-inputs.nix

@@ -19,7 +19,7 @@ let
     in
     {
       manifest = eval.config.manifest;
-      roles = lib.mapAttrs (_n: _v: { }) eval.config.roles;
+      roles = lib.mapAttrs (_n: v: { inherit (v) description; }) eval.config.roles;
     };
 in
 {