From cdbdd409216442c08772865c0ad81a37a19c4ae2 Mon Sep 17 00:00:00 2001
From: "Alan T. DeKok" <aland@freeradius.org>
Date: Thu, 14 Nov 2024 16:02:38 -0500
Subject: [PATCH] add descriptions of structural types

---
 .../reference/pages/type/all_types.adoc       | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/doc/antora/modules/reference/pages/type/all_types.adoc b/doc/antora/modules/reference/pages/type/all_types.adoc
index 8eb2b44e835d9..ec772f7db128d 100644
--- a/doc/antora/modules/reference/pages/type/all_types.adoc
+++ b/doc/antora/modules/reference/pages/type/all_types.adoc
@@ -56,10 +56,66 @@ statements.
 [cols="15%,85%"]
 |=====
 | Data Type     | Description
+| group		| generic grouping
 | struct	| structure which contains fixed-width fields
 | tlv		| type-length-value which contains other attributes
+| vendor	| Encapsulation of a vendor within data type `vsa`
 | vsa		| Encapsulation of vendor-specific attributes
 |=====
 
+Each structural data type serves a different purpose.  Each structural
+data type can contain child attributes.  The different structural
+types have different behaviors about what kind of children they can
+contain, and how the data type is sent in a packet over the network.
+
+struct:: A `struct` contains fixed-sized data types, in a pre-defined order.
++
+The `struct` can only contain a fixed and pre-defined list of child
+attributes.  These attributes are the fields, or members, of the structure.
++
+The `struct` always encodes all of its children.  If a child is
+missing, then the relevant field is filled with zeros.
+
+group: A `group` contains an arbitrary collection of children, in any order.
++
+The `group` can contain any child attributes, so long as they are
+within the same protocol namespace.  See the
+dictionary/attribute.adoc[ATTRIBUTE] documentation for more
+information.
++
+The `group` only encodes the child attributes which have been created
+and stored within the `group`.  The order of children does not matter.
+
+tlv:: A `tlv` is a `group` which has a limited subset of children.
++
+The `tlv` can only contain child attributes which have been defined as
+children of the `tlv.`
++
+The `tlv` only encodes the child attributes which have been created
+and stored within the `tlv`.  The order of children does not matter.
+
+vendor:: A `vendor` is a group which has a limited subset of children:
+attributes which have been defined by that vendor.
++
+The `vendor` can only contain child attributes which have been defined by the vendor.
++
+The `vendor` only encodes the child attributes which have been created
+and stored within the `vendor`.  The order of children does not
+matter.  In practice, the `vendor` attributes are usually encoded with
+a 32-bit vendor ID, which identies the vendor.
++
+A `vendor` data type can only be a child of a `vsa` data type.
+
+vsa:: A `vsa` is a group which has a limited subset of children: `vendor`s.
++
+The `vsa` can only contain child attributes which are `vendor`s
++
+The `vsa` only encodes the vendor attributes which have been created
+and stored within the `vsa`.  The order of children does not
+matter.
++
+A `vsa` data type can only be a contain children of the `vendor` data type.
+
+
 // Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
 // This documentation was developed by Network RADIUS SAS