docs(schema): Document newtypes

Author: epage

src/cargo/util_schemas/manifest.rs

@@ -1112,6 +1112,7 @@ impl TomlTarget {
 
 macro_rules! str_newtype {
     ($name:ident) => {
+        /// Verified string newtype
         #[derive(Serialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
         #[serde(transparent)]
         pub struct $name<T: AsRef<str> = String>(T);
@@ -1171,13 +1172,17 @@ macro_rules! str_newtype {
 str_newtype!(PackageName);
 
 impl<T: AsRef<str>> PackageName<T> {
+    /// Validated package name
     pub fn new(name: T) -> Result<Self> {
         restricted_names::validate_package_name(name.as_ref(), "package name", "")?;
         Ok(Self(name))
     }
 }
 
 impl PackageName {
+    /// Coerce a value to be a validate package name
+    ///
+    /// Replaces invalid values with `placeholder`
     pub fn sanitize(name: impl AsRef<str>, placeholder: char) -> Self {
         PackageName(restricted_names::sanitize_package_name(
             name.as_ref(),
@@ -1189,6 +1194,7 @@ impl PackageName {
 str_newtype!(RegistryName);
 
 impl<T: AsRef<str>> RegistryName<T> {
+    /// Validated registry name
     pub fn new(name: T) -> Result<Self> {
         restricted_names::validate_package_name(name.as_ref(), "registry name", "")?;
         Ok(Self(name))
@@ -1198,6 +1204,7 @@ impl<T: AsRef<str>> RegistryName<T> {
 str_newtype!(ProfileName);
 
 impl<T: AsRef<str>> ProfileName<T> {
+    /// Validated profile name
     pub fn new(name: T) -> Result<Self> {
         restricted_names::validate_profile_name(name.as_ref())?;
         Ok(Self(name))
@@ -1207,6 +1214,7 @@ impl<T: AsRef<str>> ProfileName<T> {
 str_newtype!(FeatureName);
 
 impl<T: AsRef<str>> FeatureName<T> {
+    /// Validated feature name
     pub fn new(name: T) -> Result<Self> {
         restricted_names::validate_feature_name(name.as_ref())?;
         Ok(Self(name))