Uploaded image for project: 'RHEL'
  1. RHEL
  2. RHEL-2465

Improve nm-settings-nmcli manpage to show format and valid values of properties

    • NetworkManager-1.45.3-1.el9
    • None
    • 2
    • rhel-sst-network-management
    • 7
    • 1
    • QE ack
    • False
    • Hide

      None

      Show
      None
    • 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

              ihuguet@redhat.com Inigo Huguet
              fge@redhat.com Gris Ge
              Network Management Team Network Management Team
              David Jaša David Jaša
              Votes:
              0 Vote for this issue
              Watchers:
              9 Start watching this issue

                Created:
                Updated:
                Resolved: