Documentation Traits

This wiki contains a mapping between Smithy Documentation traits and generated Ruby code.

Generated SDKs depend on yard for documentation.

deprecated trait

Marks a shape or member as deprecated. The @deprecated trait supports a message and a since property. For shapes or members that have this trait, the @deprecated yard tag is used.

@deprecated(message: "This shape is no longer used.", since: "1.3")
string OtherString

The generated code is:

# @!attribute other_string
#   @deprecated
#     This shape is no longer used.
#     Since: 1.3
#   @return [String]
MyOperationInput = ::Struct.new(
  :other_string,
  keyword_init: true
)

Otherwise, the @deprecated tag is applied on the: Client class, Client operations, Types, paginators and waiters.

See Smithy Documentation for more details.

documentation trait

Adds documentation to a shape or member using the CommonMark format. For shapes or members that have this trait, a Ruby comment is attached to it, and yard will automatically apply it.

@documentation("This *is* documentation about the shape.")
string MyString

The generated code is:

# @!attribute my_string
#   This *is* documentation about the shape.
#   @return [String]
MyOperationInput = ::Struct.new(
  :my_string,
  keyword_init: true
)

See Smithy Documentation for more details.

examples trait

Provides example inputs and outputs for operations. The @examples trait supports title, documentation, input, output, and error properties. For operations that have this trait, yard's @example tag is used. The @example tag takes the title property, and the example code block takes the documentation property as a comment (within the documentation comment). The output is shown as a Hash.

@readonly
operation MyOperation {
    input: MyOperationInput,
    output: MyOperationOutput,
    errors: [MyOperationError]
}

apply MyOperation @examples([
    {
        title: "Invoke MyOperation",
        documentation: "This is some documentation\nfor MyOperation."
        input: {
            foo: "baz"
        },
        output: {
            status: "PENDING",
        }
    },
    {
        title: "Error example for MyOperation",
        documentation: "Whoopsie poopsie!\nThis is an error you can get."
        input: {
            foo: "!"
        },
        error: {
            shapeId: MyOperationError,
            content: {
                message: "Invalid 'foo'"
            }
        }
    }
])

The generated code is:

# client.rb

# ...
# @example Invoke MyOperation
#   # This is some documentation
#   # for MyOperation.
#   resp = client.my_operation({
#     foo: "baz"
#   })
#
#   # resp.to_h outputs the following:
#   {
#     status: "PENDING"
#   }
# @example Error example for MyOperation
#   begin
#     # Whoopsie poopsie!
#     # This is an error you can get.
#     resp = client.my_operation({
#       foo: "!"
#     })
#   rescue ApiError => e
#     puts e.class # MyOperationError
#     puts e.data.to_h
#   end
#
#   # e.data.to_h outputs the following:
#   {
#     message: "Invalid 'foo'"
#   }
# ...
def my_operation(params = {}, options = {})
  ...
end

See Smithy Documentation for more details.

externalDocumentation trait

Provides named links to external documentation for a shape. This trait directly maps to yard's @see tag. The keys used in this trait are the @see tag descriptions for the value.

@externalDocumentation(
    "Homepage": "https://www.example.com/",
    "API Reference": "https://www.example.com/api-ref"
)
service MyService {
    version: "2006-03-01"
}

The generated code is:

# @see https://www.example.com/ Homepage
# @see https://www.example.com/api-ref API Reference
module MyService
  ...
end

See Smithy Documentation for more details.

internal trait

Shapes marked with the @internal trait are meant only for internal use. Shapes with the @internal trait have a yard @note documenting that the member is internal only. The code generator can optionally filter out @internal shapes not intended for external customers.

structure MyOperationInput {
    foo: String,

    @internal
    bar: String,
}

The generated code is:

# @!attribute bar
#   @note
#     This shape is meant for internal use only.
#   @return [String]
MyOperationInput = ::Struct.new(
  :foo,
  :bar,
  keyword_init: true
) 

See Smithy Documentation for more details.

recommended trait

Indicates that a structure member SHOULD be set. This trait is useful when the majority of use cases for a structure benefit from providing a value for a member, but the member is not actually required or cannot be made required backward compatibly.

structure PutContentsInput {
    @required
    contents: String,

    @recommended(reason: "Validation will reject contents if they are invalid.")
    validateContents: Boolean,
}

The generated code is:

# ...
# @!attribute validate_contents
#   @note
#     This shape is recommended.
#     Reason: Validation will reject contents if they are invalid.".
PutContentsInput = Struct.new(
  :contents,
  :validate_contents,
  keyword_init: true
)

See Smithy Documentation for more details.

sensitive trait

Indicates that the data stored in the shape or member is sensitive and MUST be handled with care. The yard @note tag is used to indicate that the shape's member is sensitive. Sensitive member values are excluded from exceptions and log output.

@sensitive
string MyString

The generated code is:

# @!method initialize(params = {})
#   @param [Hash] params
#   @option params [String] :my_string
# @!attribute my_string
#   @return [String]
MyOperationInput = ::Struct.new(
  :my_string,
  keyword_init: true
..

  def to_s
    "#<struct MyService::Types::MyOperationInput "\
      "my_string=\"[SENSITIVE]\">"
  end
end

See Smithy Documentation for more details.

since trait

Defines the version or date in which a shape or member was added to the model. The @since yard tag is used.

@since("1.3")
string MyString

The generated code is:

# @!attribute my_string
#   @since 1.3
#   @return [String]
MyOperationInput = ::Struct.new(
  :my_string,
  keyword_init: true
) do

See Smithy Documentation for more details.

tags trait

Tags a shape with arbitrary tag names that can be used to filter and group shapes in the model.

@tags(["experimental", "public"])
structure MyOperationInput {
    my_string: MyString
}

@tags(["foo"])
string MyString

A docstring will be added with the tags:

# Tags: ["experimental", "public"]
# @!method initialize(params = {})
#   @param [Hash] params
#   @option params [String] :my_string
# @!attribute my_string
#   Tags: ["foo"]
#   @return [String]
MyOperationInput = ::Struct.new(
  :my_string,
  keyword_init: true
) 

See Smithy Documentation for more details.

title trait

Defines a proper name for a service or resource shape. This title can be used in automatically generated documentation and other contexts to provide a user friendly name for services and resources. This tag's value is passed to yard's --title option when generating documentation.

namespace acme.example

@title("ACME Simple Image Service")
service MySimpleImageService {
    version: "2006-03-01"
}

A .yardopts file is generated:

--title "ACME Simple Image Service"

See Smithy Documentation for more details.

unstable trait

Indicates a shape is unstable and MAY change in the future. This trait can be applied to trait shapes to indicate that a trait is unstable or experimental. The code generator outputs a warning when code is generated with this trait. Yard's @note tag is used to indicate the shape as unstable.

@unstable
string MyString

The generated code is:

# @!attribute my_string
#   @note
#     This shape is unstable and may change in the future.
#   @return [String]
MyOperationInput = ::Struct.new(
  :my_string,
  keyword_init: true
)

See Smithy Documentation for more details.