-
Story
-
Resolution: Done-Errata
-
Undefined
-
rhel-9.4
-
NetworkManager-1.45.3-1.el9
-
None
-
2
-
rhel-sst-network-management
-
7
-
1
-
QE ack
-
False
-
-
No
-
NMT - RHEL 8.10/9.4 DTM 00, NMT - RHEL 8.10/9.4 DTM 2
-
None
In nm-settings-nmcli, many properties are not well documented regarding the value's format and the accepted values.
- The format is many times inaccurate (i.e. uint32 instead of an enum)
- The accepted values are only documented in a manual way in some properties but not in others
- The same for special and/or aliased values (i.e. uint properties that accept "unknown" or "-1" as special value)
Properly document all this information for all the properties in nm-setting-nmcli.
Also, in the description texts, many times there appear references to C enum's value names, like `NM_IP_TUNNEL_MODE_IPIP (1)`. Those names are no meaningful for a nmcli user, so the values accepted by nmcli should appear instead, like `ipip (1)`.
Acceptance criteria:
Given The nm-settings-nmcli man page
When: there is a property of any type
Then: the “Format” field must show `bool / ternary / (u)int32/64 / string / EnumName (int32)` or other concise but descriptive text
When: there is a property that accept a list of elements of any type
Then: the “Format” field must show `list of` followed by the same format text than the type of the element’s type
When: there is a property that accepts any value of its type
Then: the field “Valid values” must not appear
When: there is a property without special/aliased values
Then: the field “Special values” must not appear
When: there is a property of type integer with a range of valid values
Then: the “Valid values” field must show `MIN - MAX`
When: there is a property of type integer or enum with a limited set of valid values
Then: the “Valid values” field must show `val_nick1 (NUM1), val_nick2 (NUM2) …`
When: there is a property of type flags
Then: the “Valid values” field must show `0x1 (flag_name1), 0x2 (flag_name2) …`
When: there is a property of type string with a limited set of valid values
Then: the “Valid values” field must show `val1, val2, val3, …`
When: there is a property of type integer or enum with special/aliased values:
Then: the “Special values” field must show `val_nick1 (NUM1), val_nick2 (NUM2) …`{}
When: there is a value of the enum marked as “internal”
Then: the value is not shown in the autogenerated documentation
When: a constant value is referenced in the sources' documentation comments
Then: it should appear in the man page with the format `value_nick (num)`
Definition of done:
- The nm-settings-nmcli man page contains the information described in the acceptance criteria for every property
- links to
-
RHBA-2023:120156 NetworkManager bug fix and enhancement update