Skip to content

Commit e2bf09f

Browse files
david-perezdavid-perez
committed
Improve RustDocs for constrained types
* We decided not to generate `parse` method in #1342. * Fix link to `try_from` constructor. * Always mention the type is the result of a constrained shape, even if the shape has no documentation.
1 parent 30c6828 commit e2bf09f

File tree

6 files changed

+38
-23
lines changed

6 files changed

+38
-23
lines changed

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/ConstraintViolationSymbolProvider.kt

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,21 @@ class ConstraintViolationSymbolProvider(
7777
false -> Visibility.PUBCRATE
7878
}
7979

80-
private fun Shape.shapeModule() = RustModule.new(
81-
// need to use the context name so we get the correct name for maps
82-
name = RustReservedWords.escapeIfNeeded(this.contextName(serviceShape)).toSnakeCase(),
83-
visibility = visibility,
84-
parent = ModelsModule,
85-
inline = true,
86-
)
80+
private fun Shape.shapeModule(): RustModule.LeafModule {
81+
val documentation = if (publicConstrainedTypes && this.isDirectlyConstrained(base)) {
82+
"See [`${this.contextName(serviceShape)}`]."
83+
} else {
84+
null
85+
}
86+
return RustModule.new(
87+
// Need to use the context name so we get the correct name for maps.
88+
name = RustReservedWords.escapeIfNeeded(this.contextName(serviceShape)).toSnakeCase(),
89+
visibility = visibility,
90+
parent = ModelsModule,
91+
inline = true,
92+
documentation = documentation,
93+
)
94+
}
8795

8896
private fun constraintViolationSymbolForCollectionOrMapOrUnionShape(shape: Shape): Symbol {
8997
check(shape is CollectionShape || shape is MapShape || shape is UnionShape)

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ConstrainedCollectionGenerator.kt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,8 @@ class ConstrainedCollectionGenerator(
8585
"ConstraintViolation" to constraintViolation,
8686
)
8787

88-
writer.documentShape(shape, model, note = rustDocsNote(name))
88+
writer.documentShape(shape, model)
89+
writer.docs(rustDocsConstrainedTypeEpilogue(name))
8990
constrainedTypeMetadata.render(writer)
9091
writer.rustTemplate(
9192
"""

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ConstrainedMapGenerator.kt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import software.amazon.smithy.rust.codegen.core.rustlang.Attribute
1414
import software.amazon.smithy.rust.codegen.core.rustlang.RustMetadata
1515
import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter
1616
import software.amazon.smithy.rust.codegen.core.rustlang.Visibility
17+
import software.amazon.smithy.rust.codegen.core.rustlang.docs
1718
import software.amazon.smithy.rust.codegen.core.rustlang.documentShape
1819
import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate
1920
import software.amazon.smithy.rust.codegen.core.smithy.RuntimeType
@@ -74,7 +75,8 @@ class ConstrainedMapGenerator(
7475
"ConstraintViolation" to constraintViolation,
7576
)
7677

77-
writer.documentShape(shape, model, note = rustDocsNote(name))
78+
writer.documentShape(shape, model)
79+
writer.docs(rustDocsConstrainedTypeEpilogue(name))
7880
constrainedTypeMetadata.render(writer)
7981
writer.rustTemplate("struct $name(pub(crate) $inner);", *codegenScope)
8082
if (constrainedTypeVisibility == Visibility.PUBCRATE) {

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ConstrainedNumberGenerator.kt

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ class ConstrainedNumberGenerator(
7171
val rangeTrait = shape.expectTrait<RangeTrait>()
7272

7373
val symbol = constrainedShapeSymbolProvider.toSymbol(shape)
74-
val constrainedTypeName = symbol.name
74+
val name = symbol.name
7575
val unconstrainedTypeName = unconstrainedType.render()
7676
val constraintViolation = constraintViolationSymbolProvider.toSymbol(shape)
7777
val constraintsInfo = listOf(Range(rangeTrait).toTraitInfo(unconstrainedTypeName))
@@ -94,16 +94,17 @@ class ConstrainedNumberGenerator(
9494
visibility = constrainedTypeVisibility,
9595
)
9696

97-
writer.documentShape(shape, model, note = rustDocsNote(constrainedTypeName))
97+
writer.documentShape(shape, model)
98+
writer.docs(rustDocsConstrainedTypeEpilogue(name))
9899
constrainedTypeMetadata.render(writer)
99-
writer.rust("struct $constrainedTypeName(pub(crate) $unconstrainedTypeName);")
100+
writer.rust("struct $name(pub(crate) $unconstrainedTypeName);")
100101

101102
if (constrainedTypeVisibility == Visibility.PUBCRATE) {
102103
Attribute.AllowUnused.render(writer)
103104
}
104105
writer.rustTemplate(
105106
"""
106-
impl $constrainedTypeName {
107+
impl $name {
107108
/// ${rustDocsInnerMethod(unconstrainedTypeName)}
108109
pub fn inner(&self) -> &$unconstrainedTypeName {
109110
&self.0
@@ -115,7 +116,7 @@ class ConstrainedNumberGenerator(
115116
}
116117
}
117118
118-
impl #{ConstrainedTrait} for $constrainedTypeName {
119+
impl #{ConstrainedTrait} for $name {
119120
type Unconstrained = $unconstrainedTypeName;
120121
}
121122
@@ -125,14 +126,14 @@ class ConstrainedNumberGenerator(
125126
}
126127
}
127128
128-
impl #{Display} for $constrainedTypeName {
129+
impl #{Display} for $name {
129130
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
130131
${shape.redactIfNecessary(model, "self.0")}.fmt(f)
131132
}
132133
}
133134
134-
impl #{From}<$constrainedTypeName> for $unconstrainedTypeName {
135-
fn from(value: $constrainedTypeName) -> Self {
135+
impl #{From}<$name> for $unconstrainedTypeName {
136+
fn from(value: $name) -> Self {
136137
value.into_inner()
137138
}
138139
}
@@ -146,7 +147,7 @@ class ConstrainedNumberGenerator(
146147
"AsRef" to RuntimeType.AsRef,
147148
)
148149

149-
writer.renderTryFrom(unconstrainedTypeName, constrainedTypeName, constraintViolation, constraintsInfo)
150+
writer.renderTryFrom(unconstrainedTypeName, name, constraintViolation, constraintsInfo)
150151

151152
writer.withInlineModule(constraintViolation.module()) {
152153
rust(

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ConstrainedShapeGeneratorCommon.kt

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ package software.amazon.smithy.rust.codegen.server.smithy.generators
99
* Functions shared amongst the constrained shape generators, to keep them DRY and consistent.
1010
*/
1111

12-
fun rustDocsNote(typeName: String) =
13-
"this is a constrained type because its corresponding modeled Smithy shape has one or more " +
14-
"[constraint traits]. Use [`parse`] or [`$typeName::TryFrom`] to construct values of this type." +
15-
"[constraint traits]: https://awslabs.github.io/smithy/1.0/spec/core/constraint-traits.html"
12+
fun rustDocsConstrainedTypeEpilogue(typeName: String) = """
13+
This is a constrained type because its corresponding modeled Smithy shape has one or more
14+
[constraint traits]. Use [`$typeName::try_from`] to construct values of this type.
15+
16+
[constraint traits]: https://awslabs.github.io/smithy/1.0/spec/core/constraint-traits.html
17+
"""
1618

1719
fun rustDocsTryFromMethod(typeName: String, inner: String) =
1820
"Constructs a `$typeName` from an [`$inner`], failing when the provided value does not satisfy the modeled constraints."

‎codegen-server/src/main/kotlin/software/amazon/smithy/rust/codegen/server/smithy/generators/ConstrainedStringGenerator.kt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,8 @@ class ConstrainedStringGenerator(
8181
// Note that we're using the linear time check `chars().count()` instead of `len()` on the input value, since the
8282
// Smithy specification says the `length` trait counts the number of Unicode code points when applied to string shapes.
8383
// https://awslabs.github.io/smithy/1.0/spec/core/constraint-traits.html#length-trait
84-
writer.documentShape(shape, model, note = rustDocsNote(name))
84+
writer.documentShape(shape, model)
85+
writer.docs(rustDocsConstrainedTypeEpilogue(name))
8586
constrainedTypeMetadata.render(writer)
8687
writer.rust("struct $name(pub(crate) $inner);")
8788
if (constrainedTypeVisibility == Visibility.PUBCRATE) {

0 commit comments

Comments
 (0)