Skip to content

Commit fcb7fef

Browse files
author
Matt Muller
committed
Handle unstable trait
1 parent 0804b1f commit fcb7fef

11 files changed

Lines changed: 135 additions & 57 deletions

File tree

‎gems/smithy/lib/smithy/model/yard.rb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@ def title_docstring(title)
5151
"@title #{escape(title)}"
5252
end
5353

54+
def unstable_docstring
55+
'@note This shape is unstable and may change in future releases.'
56+
end
57+
5458
private
5559

5660
def type(service, model, id, shape) # rubocop:disable Metrics/CyclomaticComplexity

‎gems/smithy/lib/smithy/views/client/client.rb‎

Lines changed: 35 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,13 @@ def docstrings # rubocop:disable Metrics/AbcSize
108108
lines = []
109109
lines.concat(documentation_docstrings)
110110
lines.concat(params_docstrings)
111-
lines.concat(return_docstrings)
112111
lines.concat(OperationExamples.new(@model, method_name, @operation).docstrings)
113112
lines.concat(RequestResponseExample.new(@model, method_name, @operation).docstrings)
114113
lines.concat(deprecated_docstrings)
115114
lines.concat(external_documentation_docstrings)
116115
lines.concat(since_docstrings)
116+
lines.concat(unstable_docstrings)
117+
lines.concat(return_docstrings)
117118
lines
118119
end
119120

@@ -123,31 +124,10 @@ def method_name
123124

124125
private
125126

126-
def deprecated_docstrings
127-
return [] unless @traits.key?('smithy.api#deprecated')
128-
129-
message = @traits['smithy.api#deprecated'].fetch('message', '')
130-
since = @traits['smithy.api#deprecated'].fetch('since', '')
131-
Model::YARD.deprecated_docstrings(message, since)
132-
end
133-
134127
def documentation_docstrings
135128
@traits.fetch('smithy.api#documentation', '').split("\n")
136129
end
137130

138-
def external_documentation_docstrings
139-
return [] unless @traits.key?('smithy.api#externalDocumentation')
140-
141-
hash = @traits.fetch('smithy.api#externalDocumentation', {})
142-
Model::YARD.external_documentation_docstrings(hash)
143-
end
144-
145-
def since_docstrings
146-
return [] unless @traits.key?('smithy.api#since')
147-
148-
[Model::YARD.since_docstring(@traits['smithy.api#since'])]
149-
end
150-
151131
def params_docstrings
152132
input_target = @operation['input']['target']
153133
input = Model.shape(@model, input_target)
@@ -169,18 +149,45 @@ def params_docstrings
169149
lines
170150
end
171151

172-
def return_docstrings
173-
output_target = @operation['output']['target']
174-
output = Model.shape(@model, output_target)
175-
[Model::YARD.return_docstring(@service, @model, output_target, output)]
176-
end
177-
178152
def param_docstrings(member_shape, target)
179153
documentation = member_shape.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
180154
return documentation unless documentation.empty?
181155

182156
target.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
183157
end
158+
159+
def deprecated_docstrings
160+
return [] unless @traits.key?('smithy.api#deprecated')
161+
162+
message = @traits['smithy.api#deprecated'].fetch('message', '')
163+
since = @traits['smithy.api#deprecated'].fetch('since', '')
164+
Model::YARD.deprecated_docstrings(message, since)
165+
end
166+
167+
def external_documentation_docstrings
168+
return [] unless @traits.key?('smithy.api#externalDocumentation')
169+
170+
hash = @traits.fetch('smithy.api#externalDocumentation', {})
171+
Model::YARD.external_documentation_docstrings(hash)
172+
end
173+
174+
def since_docstrings
175+
return [] unless @traits.key?('smithy.api#since')
176+
177+
[Model::YARD.since_docstring(@traits['smithy.api#since'])]
178+
end
179+
180+
def unstable_docstrings
181+
return [] unless @traits.key?('smithy.api#unstable')
182+
183+
[Model::YARD.unstable_docstring]
184+
end
185+
186+
def return_docstrings
187+
output_target = @operation['output']['target']
188+
output = Model.shape(@model, output_target)
189+
[Model::YARD.return_docstring(@service, @model, output_target, output)]
190+
end
184191
end
185192
end
186193
end

‎gems/smithy/lib/smithy/views/client/module.rb‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ def docstrings
4141
lines.concat(deprecated_docstrings)
4242
lines.concat(external_documentation_docstrings)
4343
lines.concat(since_docstrings)
44+
lines.concat(unstable_docstrings)
4445
lines
4546
end
4647

@@ -64,6 +65,12 @@ def relative_requires
6465

6566
private
6667

68+
def title_docstrings
69+
return [] unless @traits.key?('smithy.api#title')
70+
71+
[Model::YARD.title_docstring(@traits['smithy.api#title'])]
72+
end
73+
6774
def documentation_docstrings
6875
@traits.fetch('smithy.api#documentation', '').split("\n")
6976
end
@@ -89,10 +96,10 @@ def since_docstrings
8996
[Model::YARD.since_docstring(@traits['smithy.api#since'])]
9097
end
9198

92-
def title_docstrings
93-
return [] unless @traits.key?('smithy.api#title')
99+
def unstable_docstrings
100+
return [] unless @traits.key?('smithy.api#unstable')
94101

95-
[Model::YARD.title_docstring(@traits['smithy.api#title'])]
102+
[Model::YARD.unstable_docstring]
96103
end
97104
end
98105
end

‎gems/smithy/lib/smithy/views/client/types.rb‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ def docstrings
5151
lines.concat(external_documentation_docstrings)
5252
lines.concat(sensitive_docstrings)
5353
lines.concat(since_docstrings)
54+
lines.concat(unstable_docstrings)
5455
lines
5556
end
5657

@@ -62,6 +63,10 @@ def attribute_docstrings
6263
lines
6364
end
6465

66+
def documentation_docstrings
67+
@traits.fetch('smithy.api#documentation', '').split("\n")
68+
end
69+
6570
def deprecated_docstrings
6671
return [] unless @traits.key?('smithy.api#deprecated')
6772

@@ -70,10 +75,6 @@ def deprecated_docstrings
7075
Model::YARD.deprecated_docstrings(message, since)
7176
end
7277

73-
def documentation_docstrings
74-
@traits.fetch('smithy.api#documentation', '').split("\n")
75-
end
76-
7778
def external_documentation_docstrings
7879
return [] unless @traits.key?('smithy.api#externalDocumentation')
7980

@@ -92,6 +93,12 @@ def since_docstrings
9293

9394
[Model::YARD.since_docstring(@traits['smithy.api#since'])]
9495
end
96+
97+
def unstable_docstrings
98+
return [] unless @traits.key?('smithy.api#unstable')
99+
100+
[Model::YARD.unstable_docstring]
101+
end
95102
end
96103

97104
# @api private
@@ -118,10 +125,18 @@ def docstrings # rubocop:disable Metrics/AbcSize
118125
lines.concat(indented_docstrings(external_documentation_docstrings))
119126
lines.concat(indented_docstrings(recommended_docstrings))
120127
lines.concat(indented_docstrings(since_docstrings))
128+
lines.concat(indented_docstrings(unstable_docstrings))
121129
lines.concat(indented_docstrings(return_docstrings))
122130
lines
123131
end
124132

133+
def documentation_docstrings
134+
lines = @member.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
135+
return lines unless lines.empty?
136+
137+
@target.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
138+
end
139+
125140
def deprecated_docstrings
126141
return [] unless @traits.key?('smithy.api#deprecated')
127142

@@ -130,13 +145,6 @@ def deprecated_docstrings
130145
Model::YARD.deprecated_docstrings(message, since)
131146
end
132147

133-
def documentation_docstrings
134-
lines = @member.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
135-
return lines unless lines.empty?
136-
137-
@target.fetch('traits', {}).fetch('smithy.api#documentation', '').split("\n")
138-
end
139-
140148
def external_documentation_docstrings
141149
return [] unless @traits.key?('smithy.api#externalDocumentation')
142150

@@ -151,16 +159,22 @@ def recommended_docstrings
151159
Model::YARD.recommended_docstrings(reason)
152160
end
153161

154-
def return_docstrings
155-
[Model::YARD.return_docstring(@service, @model, @member['target'], @target)]
156-
end
157-
158162
def since_docstrings
159163
return [] unless @traits.key?('smithy.api#since')
160164

161165
[Model::YARD.since_docstring(@traits['smithy.api#since'])]
162166
end
163167

168+
def unstable_docstrings
169+
return [] unless @traits.key?('smithy.api#unstable')
170+
171+
[Model::YARD.unstable_docstring]
172+
end
173+
174+
def return_docstrings
175+
[Model::YARD.return_docstring(@service, @model, @member['target'], @target)]
176+
end
177+
164178
def default?
165179
traits = @member.fetch('traits', {})
166180
traits.key?('smithy.api#default') && !traits.key?('smithy.api#clientOptional')

‎gems/smithy/spec/fixtures/documentation/model.json‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@
2424
"Service link": "https://www.example.com/"
2525
},
2626
"smithy.api#since": "1.0",
27-
"smithy.api#title": "Documentation Test"
27+
"smithy.api#title": "Documentation Test",
28+
"smithy.api#unstable": {}
2829
}
2930
},
3031
"smithy.ruby.tests#Foo": {
@@ -44,7 +45,8 @@
4445
"smithy.api#recommended": {
4546
"reason": "This is recommended"
4647
},
47-
"smithy.api#since": "2.0"
48+
"smithy.api#since": "2.0",
49+
"smithy.api#unstable": {}
4850
}
4951
},
5052
"bar": {
@@ -67,7 +69,8 @@
6769
"Structure link": "https://www.example.com/"
6870
},
6971
"smithy.api#sensitive": {},
70-
"smithy.api#since": "1.0"
72+
"smithy.api#since": "1.0",
73+
"smithy.api#unstable": {}
7174
}
7275
},
7376
"smithy.ruby.tests#Operation": {
@@ -87,7 +90,8 @@
8790
"smithy.api#externalDocumentation": {
8891
"Operation link": "https://www.example.com/"
8992
},
90-
"smithy.api#since": "1.0"
93+
"smithy.api#since": "1.0",
94+
"smithy.api#unstable": {}
9195
}
9296
},
9397
"smithy.ruby.tests#Structure": {

‎gems/smithy/spec/fixtures/documentation/model.smithy‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ namespace smithy.ruby.tests
77
@externalDocumentation("Service link": "https://www.example.com/")
88
@since("1.0")
99
@title("Documentation Test")
10+
@unstable
1011
service Documentation {
1112
operations: [Operation]
1213
}
@@ -15,6 +16,7 @@ service Documentation {
1516
@documentation("Operation documentation")
1617
@externalDocumentation("Operation link": "https://www.example.com/")
1718
@since("1.0")
19+
@unstable
1820
operation Operation {
1921
input: Foo
2022
output: Foo
@@ -25,12 +27,14 @@ operation Operation {
2527
@externalDocumentation("Structure link": "https://www.example.com/")
2628
@sensitive
2729
@since("1.0")
30+
@unstable
2831
structure Foo {
2932
@deprecated(message: "Deprecated structure member", since: "2.0")
3033
@documentation("Member documentation")
3134
@externalDocumentation("Member link": "https://www.example.com/")
3235
@recommended(reason: "This is recommended")
3336
@since("2.0")
37+
@unstable
3438
baz: Baz
3539

3640
@required

‎gems/smithy/spec/interfaces/client/client_spec.rb‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,6 @@ def assert(expected)
7878
@option params [String] :bar
7979
Shape documentation
8080
@option params [Types::Structure] :qux
81-
@return [Types::OperationOutput]
8281
DOC
8382
assert(expected)
8483
end
@@ -103,6 +102,13 @@ def assert(expected)
103102
DOC
104103
assert(expected)
105104
end
105+
106+
it 'generates unstable documentation' do
107+
expected = <<~DOC
108+
@note This shape is unstable and may change in future releases.
109+
DOC
110+
assert(expected)
111+
end
106112
end
107113

108114
context 'examples trait' do

‎gems/smithy/spec/interfaces/client/module_spec.rb‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,12 @@ def assert(expected)
5353
DOC
5454
assert(expected)
5555
end
56+
57+
it 'generates unstable documentation' do
58+
expected = <<~DOC
59+
@note This shape is unstable and may change in future releases.
60+
DOC
61+
assert(expected)
62+
end
5663
end
5764
end

‎gems/smithy/spec/interfaces/client/types_spec.rb‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,13 @@ def assert(expected)
5656
assert(expected)
5757
end
5858

59+
it 'generates unstable documentation' do
60+
expected = <<~DOC
61+
@note This shape is unstable and may change in future releases.
62+
DOC
63+
assert(expected)
64+
end
65+
5966
it 'generates attribute documentation' do
6067
expected = <<~DOC
6168
@!attribute baz
@@ -68,6 +75,7 @@ def assert(expected)
6875
This shape is recommended
6976
Reason: This is recommended
7077
@since 2.0
78+
@note This shape is unstable and may change in future releases.
7179
@return [String]
7280
@!attribute bar
7381
Shape documentation

0 commit comments

Comments
 (0)