docs: Improve description of overrides nodes

We no longer limit them to lock file usage, though care as to be taken
when combining manually set ones with those. Furthermore add
descriptions for the recently added URL property.

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>

Author: jan-kiszka

docs/userguide/project-configuration.rst

@@ -406,14 +406,19 @@ Configuration reference
   :kasschemadesc:`overrides`
 
   ``repos``: dict [optional]
-    Maps to the top-level ``repos`` entry.
+    :kasschemadesc:`overrides.properties.repos`
 
     ``<repo-id>``: dict [optional]
-      Maps to the ``<repo-id>`` entry.
+      :kasschemadesc:`overrides.properties.repos.additionalProperties.anyOf[0]`
 
-    ``commit``: string [optional]
-      Pinned commit ID which overrides the ``commit`` of the corresponding
-      repo.
+      ``branch``: string [optional]
+        :kasschemadesc:`overrides.properties.repos.additionalProperties.anyOf[0].properties.branch`
+
+      ``commit``: string [optional]
+        :kasschemadesc:`overrides.properties.repos.additionalProperties.anyOf[0].properties.commit`
+
+      ``url``: string [optional]
+        :kasschemadesc:`overrides.properties.repos.additionalProperties.anyOf[0].properties.url`
 
 ``bblayers_conf_header``: dict [optional]
   :kasschemadesc:`bblayers_conf_header`

kas/schema-kas.json

@@ -126,24 +126,28 @@
             }
         },
         "overrides": {
-            "description": "Overrides for specific configuration nodes. By that, only items that already exist are overridden. Note, that all entries below this key are reserved for auto-generation using kas plugins. Do not manually add entries.",
+            "description": "Overrides for specific configuration nodes. By that, only items that already exist are overridden. Note that the lock plugin uses overrides to manage pinning of commits. Manually added overrides can interfere with lock file generated by the plugin.",
             "type": "object",
             "additionalProperties": false,
             "properties": {
                 "repos": {
+                    "description": "Maps to the top-level ``repos`` entry.",
                     "type": "object",
                     "additionalProperties": {
+                        "description",: "Maps to the ``<repo-id>`` entry.",
                         "type": "object",
                         "additionalProperties": false,
                         "properties": {
                             "branch": {
-                                "description": "Branch in which to find the overridden commit, can be Null",
+                                "description": "Branch in which to find the overridden commit. Can be Null.",
                                 "type": ["string", "null"]
                             },
                             "commit": {
+                                "description": "Pinned commit ID which overrides the ``commit`` of the corresponding repo. Can be Null.",
                                 "type": ["string", "null"]
                             },
                             "url": {
+                                "description": "Alternative URL for the corresponding repo.",
                                 "type": "string"
                             }
                         }