Package software.amazon.smithy.docgen

Class DocSymbolProvider

java.lang.Object

software.amazon.smithy.model.shapes.ShapeVisitor.Default<Symbol>

software.amazon.smithy.docgen.DocSymbolProvider

All Implemented Interfaces:

SymbolProvider, ShapeVisitor<Symbol>

public final class DocSymbolProvider
extends ShapeVisitor.Default<Symbol>
implements SymbolProvider

Creates documentation Symbols for each shape in the model.

These symbols contain many important pieces of metadata. Particularly important are:

• name: The name of the symbol will be used as the title for its definition section. For services, this defaults to the value of the title trait. For other shapes, it defaults to the shape name including any renames from the attached service.
• definitionFile: The file in which the documentation for this shape should be written. By default these are all written to a single flat directory. If this is empty, the shape does not have its own definition section and cannot be linked to.
• SHAPE_PROPERTY: A named Shape property containing the shape that the symbol represents. Decorators provided by SmithyIntegration.decorateSymbolProvider(software.amazon.smithy.model.Model, S, software.amazon.smithy.codegen.core.SymbolProvider) MUST set or preserve this property.
• OPERATION_PROPERTY: A named OperationShape property containing the operation shape that the shape is bound to. This will only be present on structure shapes that have the input or output traits.
• LINK_ID_PROPERTY: A named String property containing the string to use for the id for links to the shape. In HTML, this would be the id for the tag containing the shape's definition. Given a link id foo, a link to the shape's definition might look like https://example.com/shapes#foo for example. If this or definitionFile is empty, it is not possible to link to the shape.
• ENABLE_DEFAULT_FILE_EXTENSION: A named boolean property indicating whether the symbol's definition file should have the default file extension applied. If not present or set to false, the file extension will not be applied.

Decorators provided by SmithyIntegration.decorateSymbolProvider(software.amazon.smithy.model.Model, S, software.amazon.smithy.codegen.core.SymbolProvider) MUST set these properties or preserve

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	DocSymbolProvider.FileExtensionDecorator	Adds file extensions to symbol definition files.

Nested classes/interfaces inherited from interface software.amazon.smithy.model.shapes.ShapeVisitor

ShapeVisitor.DataShapeVisitor<R>, ShapeVisitor.Default<R>

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ENABLE_DEFAULT_FILE_EXTENSION	A named boolean property indicating whether the symbol's definition file should have the default file extension applied.
static final String	LINK_ID_PROPERTY	The name for a shape symbol's named property containing the string to use for the id for links to the shape.
static final String	OPERATION_PROPERTY	The operation that the symbol's shape is bound to.
static final String	SHAPE_PROPERTY	The name for a shape symbol's named property containing the shape the symbol represents.

Constructor Summary

Constructors

Constructor	Description
DocSymbolProvider(Model model, DocSettings docSettings)	Constructor.

Method Summary

Modifier and Type	Method	Description
Symbol	enumShape(EnumShape shape)
protected Symbol	getDefault(Shape shape)	Returns a value for any unhandled shape.
Symbol	intEnumShape(IntEnumShape shape)
Symbol	memberShape(MemberShape shape)
Symbol	operationShape(OperationShape shape)
Symbol	resourceShape(ResourceShape shape)
Symbol	serviceShape(ServiceShape shape)
Symbol	structureShape(StructureShape shape)
Symbol	toSymbol(Shape shape)	Gets the symbol to define for the given shape.
Symbol	unionShape(UnionShape shape)

Methods inherited from class software.amazon.smithy.model.shapes.ShapeVisitor.Default

bigDecimalShape, bigIntegerShape, blobShape, booleanShape, byteShape, documentShape, doubleShape, floatShape, integerShape, listShape, longShape, mapShape, shortShape, stringShape, timestampShape

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface software.amazon.smithy.model.shapes.ShapeVisitor

setShape

Methods inherited from interface software.amazon.smithy.codegen.core.SymbolProvider

toMemberName

Field Details

SHAPE_PROPERTY

public static final String SHAPE_PROPERTY

The name for a shape symbol's named property containing the shape the symbol represents.

Decorators provided by SmithyIntegration.decorateSymbolProvider(software.amazon.smithy.model.Model, S, software.amazon.smithy.codegen.core.SymbolProvider) MUST preserve this property.

Use symbol.expectProperty(SHAPE_PROPERTY, Shape.class) to access this property.

See Also:

• Constant Field Values

OPERATION_PROPERTY

public static final String OPERATION_PROPERTY

The operation that the symbol's shape is bound to.

This property will only be present on structures that have either the input or output trait.

Use symbol.getProperty(OPERATION_PROPERTY, OperationShape.class) to access this property.

See Also:

• Constant Field Values

LINK_ID_PROPERTY

public static final String LINK_ID_PROPERTY

The name for a shape symbol's named property containing the string to use for the id for links to the shape. In HTML, this would be the id for the tag containing the shape's definition. Given a link id foo, a link to the shape's definition might look like https://example.com/shapes#foo for example.

If this or definitionFile is empty, it is not possible to link to the shape.

Use symbol.getProperty(LINK_ID_PROPERTY, String.class) to access this property.

See Also:

• Constant Field Values

ENABLE_DEFAULT_FILE_EXTENSION

public static final String ENABLE_DEFAULT_FILE_EXTENSION

A named boolean property indicating whether the symbol's definition file should have the default file extension applied. If not present or set to false, the file extension will not be applied.

Use symbol.getProperty(LINK_ID_PROPERTY, Boolean.class) to access this property.

See Also:

• Constant Field Values

Constructor Details

DocSymbolProvider

public DocSymbolProvider(Model model,
 DocSettings docSettings)

Constructor.

Parameters:

model - The model to provide symbols for.

docSettings - Settings used to customize symbol creation.

Method Details

toSymbol

public Symbol toSymbol(Shape shape)

Description copied from interface: SymbolProvider

Gets the symbol to define for the given shape.

A "symbol" represents the qualified name of a type in a target programming language.

• When given a structure, union, resource, or service shape, this method should provide the namespace and name of the type to generate.
• When given a simple type like a string, number, or timestamp, this method should return the language-specific type of the shape.
• When given a member shape, this method should return the language specific type to use as the target of the member.
• When given a list, set, or map, this method should return the language specific type to use for the shape (e.g., a map shape for a Python code generator might return "dict".

Specified by:

toSymbol in interface SymbolProvider

Parameters:

shape - Shape to get the class name of.

Returns:

Returns the generated class name.

serviceShape

public Symbol serviceShape(ServiceShape shape)

Specified by:

serviceShape in interface ShapeVisitor<Symbol>

Overrides:

serviceShape in class ShapeVisitor.Default<Symbol>

resourceShape

public Symbol resourceShape(ResourceShape shape)

Specified by:

resourceShape in interface ShapeVisitor<Symbol>

Overrides:

resourceShape in class ShapeVisitor.Default<Symbol>

operationShape

public Symbol operationShape(OperationShape shape)

Specified by:

operationShape in interface ShapeVisitor<Symbol>

Overrides:

operationShape in class ShapeVisitor.Default<Symbol>

structureShape

public Symbol structureShape(StructureShape shape)

Specified by:

structureShape in interface ShapeVisitor<Symbol>

Overrides:

structureShape in class ShapeVisitor.Default<Symbol>

enumShape

public Symbol enumShape(EnumShape shape)

Specified by:

enumShape in interface ShapeVisitor<Symbol>

intEnumShape

public Symbol intEnumShape(IntEnumShape shape)

Specified by:

intEnumShape in interface ShapeVisitor<Symbol>

unionShape

public Symbol unionShape(UnionShape shape)

Specified by:

unionShape in interface ShapeVisitor<Symbol>

Overrides:

unionShape in class ShapeVisitor.Default<Symbol>

memberShape

public Symbol memberShape(MemberShape shape)

Specified by:

memberShape in interface ShapeVisitor<Symbol>

Overrides:

memberShape in class ShapeVisitor.Default<Symbol>

getDefault

protected Symbol getDefault(Shape shape)

Description copied from class: ShapeVisitor.Default

Returns a value for any unhandled shape.

Specified by:

getDefault in class ShapeVisitor.Default<Symbol>

Parameters:

shape - Shape that is being visited.

Returns:

Return value.