naming and documentation fixes

roles/service/meta/argument_specs.yaml

@@ -68,7 +68,7 @@ argument_specs:
         required: false
 
       service_container_image:
-        description: "The image to run in the service container(s), in FQIN format (registry/imagename:tag)."
+        description: "The image to run in the service container(s), in FQIN format (registry/image_name:tag)."
         type: str
         required: true
 
@@ -287,7 +287,7 @@ argument_specs:
           - The password will be accessible as secret at /run/secrets/<service database type>
           - >
             The password will also be available as the
-            service_podman_secrets['{{ service_name }}-{{ service_database_type }}'] variable.
+            service_podman_secrets['<service name>-<service database type>'] variable.
         type: str
         choices:
           - postgres
@@ -366,7 +366,7 @@ argument_specs:
             description: Command to start the container with.
             type: list
             required: false
-            default: "[]"
+            default: []
             elements: str
           entrypoint:
             description: Entrypoint to use in the container
@@ -374,7 +374,7 @@ argument_specs:
             required: false
             default: ""
           mounts:
-            description: List of bind mounts or volumes to be mounted inside the main service container.
+            description: List of bind mounts or volumes to be mounted inside the container.
             type: list
             required: false
             default: "{{ service_container_mounts }}"
@@ -429,16 +429,51 @@ argument_specs:
                 required: false
                 default: []
           publish_ports:
-            description: "A list of published ports in docker format (<host listen address>:<host port>:<container port>)"
+            description: A list of ports to publish outside the container
             type: list
             required: false
             default: []
-            elements: str
+            elements: dict
+            options:
+              name:
+                description:
+                  - Name of the port.
+                  - >-
+                    If type is socket, the socket will be created at
+                    /run/<service name>-<additional container name>-<port name>.sock on the host.
+                  - If type is not socket, this is just informative.
+                type: str
+                required: true
+              container_port:
+                description: Container port to publish
+                type: int
+                required: true
+              type:
+                description: Whether to publish as a port or socket
+                type: str
+                required: false
+                default: port
+                choices:
+                  - socket
+                  - port
+              host_address:
+                description:
+                  - IP or hostname to listen on on the host
+                  - Ignored if type is socket
+                type: str
+                required: false
+                default: 0.0.0.0
+              host_port:
+                description:
+                  - Port to listen on on the host
+                  - Required if type is port, ignored otherwise
+                type: int
+                required: false
           env:
             description: A dict of environment variables for the container
             type: dict
             required: false
-            default: {}
+            default: "{{ service_container_env }}"
           add_capabilities:
             description: List of capabilities to add to the container
             type: list
@@ -456,7 +491,7 @@ argument_specs:
                 container doesn't support reading the secret from file or environment variable.
             type: list
             required: false
-            default: []
+            default: "{{ service_container_secrets }}"
             elements: dict
             options:
               name: