core/trivial: add code comment explaining route-handling and gateway

src/nm-ip4-config.c

@@ -1335,6 +1335,16 @@ nm_ip4_config_unset_gateway (NMIP4Config *config)
 	}
 }
 
+/**
+ * nm_ip4_config_has_gateway:
+ * @config: the #NMIP4Config object
+ *
+ * NetworkManager's handling of default-routes is limited and usually a default-route
+ * cannot have gateway 0.0.0.0. For peer-to-peer routes, we still want to
+ * support that, so we need to differenciate between no-default-route and a
+ * on-link-default route. Hence nm_ip4_config_has_gateway().
+ *
+ * Returns: whether the object has a gateway explicitly set. */
 gboolean
 nm_ip4_config_has_gateway (const NMIP4Config *config)
 {

src/platform/nm-platform.c

@@ -2739,6 +2739,36 @@ nm_platform_ip6_route_get_all (NMPlatform *self, int ifindex, NMPlatformGetRoute
 	return klass->ip6_route_get_all (self, ifindex, flags);
 }
 
+/**
+ * nm_platform_ip4_route_add:
+ * @self:
+ * @ifindex:
+ * @source:
+ * network:
+ * plen:
+ * gateway:
+ * pref_src:
+ * metric:
+ * mss:
+ *
+ * For kernel, a gateway can be either explicitly set or left
+ * at zero (0.0.0.0). In addition, there is the scope of the IPv4
+ * route.
+ * When adding a route with
+ *   $ ip route add default dev $IFNAME
+ * the resulting route will have gateway 0.0.0.0 and scope "link".
+ * Contrary to
+ *   $ ip route add default via 0.0.0.0 dev $IFNAME
+ * which adds the route with scope "global".
+ *
+ * NetworkManager's Platform can currently only add on-link-routes with scope
+ * "link" (and gateway 0.0.0.0) or gateway-routes with scope "global" (and
+ * gateway not 0.0.0.0).
+ *
+ * It does not support adding globally scoped routes via 0.0.0.0.
+ *
+ * Returns: %TRUE in case of success.
+ */
 gboolean
 nm_platform_ip4_route_add (NMPlatform *self,
                            int ifindex, NMIPConfigSource source,