shared/trivial: add code comment to explain NMUtilsEnumValueInfo consistency rules

1 files changed, 9 insertions, 0 deletions

diff --git a/shared/nm-utils/nm-enum-utils.c b/shared/nm-utils/nm-enum-utils.c
index 023f8385ff..b83c42078e 100644
--- a/shared/nm-utils/nm-enum-utils.c
+++ b/shared/nm-utils/nm-enum-utils.c
@@ -64,9 +64,18 @@ _ASSERT_enum_values_info (GType type,
 				 * And then, when actually running against a newer library version where
 				 * @type knows the nick, we have this situation.
 				 *
+				 * Another reason for specifying a nick both in @value_infos and @type,
+				 * is to specify an alias which is not used with highest preference. For
+				 * example, if you add an alias "disabled" for "none" (both numerically
+				 * equal), then the first alias in @value_infos will be preferred over
+				 * the name from @type. So, to still use "none" as preferred name, you may
+				 * explicitly specify the "none" alias in @value_infos before "disabled".
+				 *
 				 * However, what never is allowed, is to use a name (nick) to re-number
 				 * the value. That is, if both @value_infos and @type contain a particular
 				 * nick, their numeric values must agree as well.
+				 * Allowing this, would be very confusing, because the name would have a different
+				 * value from the regular GLib GEnum API.
 				 */
 				g_assert (enum_value->value == value_infos->value);
 			}