update comments

Created using spr 1.3.6-beta.1

common-extended/src/inventory.rs

@@ -375,7 +375,8 @@ impl ZoneKind {
     /// services.
     pub const NTP_PREFIX: &'static str = "ntp";
 
-    /// Return a string that is used to construct **zone names**.
+    /// Return a string that is used to construct **zone names**. This string
+    /// is guaranteed to be stable over time.
     pub fn zone_prefix(self) -> &'static str {
         match self {
             // BoundaryNtp and InternalNtp both use "ntp".
@@ -393,7 +394,8 @@ impl ZoneKind {
         }
     }
 
-    /// Return a string that is used to construct **SMF service names**.
+    /// Return a string that is used to construct **SMF service names**. This
+    /// string is guaranteed to be stable over time.
     pub fn service_prefix(self) -> &'static str {
         match self {
             // BoundaryNtp and InternalNtp both use "ntp".
@@ -412,7 +414,10 @@ impl ZoneKind {
         }
     }
 
-    /// Return a string suitable for use **in `Name` instances**.
+    /// Return a string suitable for use **in `Name` instances**. This string
+    /// is guaranteed to be stable over time.
+    ///
+    /// This string uses dashes rather than underscores, as required by `Name`.
     pub fn name_prefix(self) -> &'static str {
         match self {
             // BoundaryNtp and InternalNtp both use "ntp" here.
@@ -430,7 +435,10 @@ impl ZoneKind {
         }
     }
 
-    /// Return a string that is used for reporting and testing.
+    /// Return a string that is used for reporting and error messages. This is
+    /// **not guaranteed** to be stable.
+    ///
+    /// If you're displaying a user-friendly message, prefer this method.
     pub fn report_str(self) -> &'static str {
         match self {
             ZoneKind::BoundaryNtp => "boundary_ntp",

nexus/db-model/src/network_interface.rs

@@ -161,11 +161,6 @@ pub struct ServiceNetworkInterface {
 impl ServiceNetworkInterface {
     /// Generate a suitable [`Name`] for the given Omicron zone ID and kind.
     pub fn name(zone_id: OmicronZoneUuid, zone_kind: ZoneKind) -> Name {
-        // We use `as_name_str` rather than `as_service_str` here, because that
-        // uses underscores as separators which aren't allowed in `Name`s. We
-        // also preserve some existing naming behavior where NTP external
-        // networking is just called "ntp", not "boundary-ntp".
-        //
         // Most of these zone kinds do not get external networking and
         // therefore we don't need to be able to generate names for them, but
         // it's simpler to give them valid descriptions than worry about error