docs: improve field description for BridgeSTP, BridgeVLAN

Add more clarifying notes. Signed-off-by: Joakim Nohlgård <[email protected]> Signed-off-by: Andrey Smirnov <[email protected]>
siderolabs · Oct 25, 2024 · d4cb478 · d4cb478
1 parent 7329824
commit d4cb478
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 26 deletions.
diff --git a/pkg/machinery/config/schemas/config.schema.json b/pkg/machinery/config/schemas/config.schema.json
@@ -901,16 +901,16 @@
         "stp": {
           "$ref": "#/$defs/v1alpha1.STP",
           "title": "stp",
-          "description": "A bridge option.\nPlease see the official kernel documentation.\n",
-          "markdownDescription": "A bridge option.\nPlease see the official kernel documentation.",
-          "x-intellij-html-description": "\u003cp\u003eA bridge option.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
+          "description": "Enable STP on this bridge.\nPlease see the official kernel documentation.\n",
+          "markdownDescription": "Enable STP on this bridge.\nPlease see the official kernel documentation.",
+          "x-intellij-html-description": "\u003cp\u003eEnable STP on this bridge.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
         },
         "vlan": {
           "$ref": "#/$defs/v1alpha1.BridgeVLAN",
           "title": "vlan",
-          "description": "A bridge option.\nPlease see the official kernel documentation.\n",
-          "markdownDescription": "A bridge option.\nPlease see the official kernel documentation.",
-          "x-intellij-html-description": "\u003cp\u003eA bridge option.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
+          "description": "Enable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.\n",
+          "markdownDescription": "Enable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.",
+          "x-intellij-html-description": "\u003cp\u003eEnable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
         }
       },
       "additionalProperties": false,

diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go
@@ -1997,11 +1997,11 @@ type Bridge struct {
 	//   description: The interfaces that make up the bridge.
 	BridgedInterfaces []string `yaml:"interfaces"`
 	//   description: |
-	//     A bridge option.
+	//     Enable STP on this bridge.
 	//     Please see the official kernel documentation.
 	BridgeSTP *STP `yaml:"stp,omitempty"`
 	//   description: |
-	//     A bridge option.
+	//     Enable VLAN-awareness on this bridge.
 	//     Please see the official kernel documentation.
 	BridgeVLAN *BridgeVLAN `yaml:"vlan,omitempty"`
 }

diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go
diff --git a/website/content/v1.9/reference/configuration/v1alpha1/config.md b/website/content/v1.9/reference/configuration/v1alpha1/config.md
@@ -200,7 +200,7 @@ network:
           #     interfaces:
           #         - enxda4042ca9a51
           #         - enxae2a6774c259
-          #     # A bridge option.
+          #     # Enable STP on this bridge.
           #     stp:
           #         enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 
@@ -771,7 +771,7 @@ machine:
               #     interfaces:
               #         - enxda4042ca9a51
               #         - enxae2a6774c259
-              #     # A bridge option.
+              #     # Enable STP on this bridge.
               #     stp:
               #         enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 
@@ -882,7 +882,7 @@ interfaces:
       #     interfaces:
       #         - enxda4042ca9a51
       #         - enxae2a6774c259
-      #     # A bridge option.
+      #     # Enable STP on this bridge.
       #     stp:
       #         enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 
@@ -1002,7 +1002,7 @@ machine:
               #     interfaces:
               #         - enxda4042ca9a51
               #         - enxae2a6774c259
-              #     # A bridge option.
+              #     # Enable STP on this bridge.
               #     stp:
               #         enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 
@@ -1094,7 +1094,7 @@ bridge:
     interfaces:
         - enxda4042ca9a51
         - enxae2a6774c259
-    # A bridge option.
+    # Enable STP on this bridge.
     stp:
         enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 {{< /highlight >}}</details> | |
@@ -1352,7 +1352,7 @@ machine:
                 interfaces:
                     - enxda4042ca9a51
                     - enxae2a6774c259
-                # A bridge option.
+                # Enable STP on this bridge.
                 stp:
                     enabled: true # Whether Spanning Tree Protocol (STP) is enabled.
 {{< /highlight >}}
@@ -1361,8 +1361,8 @@ machine:
 | Field | Type | Description | Value(s) |
 |-------|------|-------------|----------|
 |`interfaces` |[]string |The interfaces that make up the bridge.  | |
-|`stp` |<a href="#Config.machine.network.interfaces..bridge.stp">STP</a> |<details><summary>A bridge option.</summary>Please see the official kernel documentation.</details>  | |
-|`vlan` |<a href="#Config.machine.network.interfaces..bridge.vlan">BridgeVLAN</a> |<details><summary>A bridge option.</summary>Please see the official kernel documentation.</details>  | |
+|`stp` |<a href="#Config.machine.network.interfaces..bridge.stp">STP</a> |<details><summary>Enable STP on this bridge.</summary>Please see the official kernel documentation.</details>  | |
+|`vlan` |<a href="#Config.machine.network.interfaces..bridge.vlan">BridgeVLAN</a> |<details><summary>Enable VLAN-awareness on this bridge.</summary>Please see the official kernel documentation.</details>  | |
 
 
 

diff --git a/website/content/v1.9/schemas/config.schema.json b/website/content/v1.9/schemas/config.schema.json
@@ -901,16 +901,16 @@
         "stp": {
           "$ref": "#/$defs/v1alpha1.STP",
           "title": "stp",
-          "description": "A bridge option.\nPlease see the official kernel documentation.\n",
-          "markdownDescription": "A bridge option.\nPlease see the official kernel documentation.",
-          "x-intellij-html-description": "\u003cp\u003eA bridge option.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
+          "description": "Enable STP on this bridge.\nPlease see the official kernel documentation.\n",
+          "markdownDescription": "Enable STP on this bridge.\nPlease see the official kernel documentation.",
+          "x-intellij-html-description": "\u003cp\u003eEnable STP on this bridge.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
         },
         "vlan": {
           "$ref": "#/$defs/v1alpha1.BridgeVLAN",
           "title": "vlan",
-          "description": "A bridge option.\nPlease see the official kernel documentation.\n",
-          "markdownDescription": "A bridge option.\nPlease see the official kernel documentation.",
-          "x-intellij-html-description": "\u003cp\u003eA bridge option.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
+          "description": "Enable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.\n",
+          "markdownDescription": "Enable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.",
+          "x-intellij-html-description": "\u003cp\u003eEnable VLAN-awareness on this bridge.\nPlease see the official kernel documentation.\u003c/p\u003e\n"
         }
       },
       "additionalProperties": false,