Skip to content

Commit

Permalink
Generate docs for enums
Browse files Browse the repository at this point in the history
  • Loading branch information
@JordonPhillips
JordonPhillips committed Nov 7, 2023
1 parent 3d3c1c6 commit afb1c42
Show file tree
Hide file tree
Showing 7 changed files with 93 additions and 11 deletions.
8 changes: 6 additions & 2 deletions smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DirectedDocGen.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
import software.amazon.smithy.docgen.core.generators.OperationGenerator;
import software.amazon.smithy.docgen.core.generators.ServiceGenerator;
import software.amazon.smithy.docgen.core.generators.StructuredShapeGenerator;
import software.amazon.smithy.model.node.ExpectationNotMetException;
import software.amazon.smithy.model.traits.InputTrait;
import software.amazon.smithy.model.traits.OutputTrait;
import software.amazon.smithy.utils.SmithyUnstableApi;
Expand Down Expand Up @@ -78,12 +79,15 @@ public void generateUnion(GenerateUnionDirective<DocGenerationContext, DocSettin

@Override
public void generateEnumShape(GenerateEnumDirective<DocGenerationContext, DocSettings> directive) {
// no-op for now
new StructuredShapeGenerator(directive.context()).accept(directive.shape(), MemberListingType.OPTIONS);
}

@Override
public void generateIntEnumShape(GenerateIntEnumDirective<DocGenerationContext, DocSettings> directive) {
// no-op for now
var shape = directive.shape();
var intEnum = shape.asIntEnumShape().orElseThrow(() -> new ExpectationNotMetException(
"Expected an intEnum shape, but found " + shape, shape));
new StructuredShapeGenerator(directive.context()).accept(intEnum, MemberListingType.OPTIONS);
}

@Override
Expand Down
16 changes: 16 additions & 0 deletions smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSymbolProvider.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
import software.amazon.smithy.codegen.core.SymbolProvider;
import software.amazon.smithy.model.Model;
import software.amazon.smithy.model.knowledge.OperationIndex;
import software.amazon.smithy.model.shapes.EnumShape;
import software.amazon.smithy.model.shapes.IntEnumShape;
import software.amazon.smithy.model.shapes.MemberShape;
import software.amazon.smithy.model.shapes.OperationShape;
import software.amazon.smithy.model.shapes.ServiceShape;
Expand Down Expand Up @@ -199,6 +201,20 @@ public Symbol structureShape(StructureShape shape) {
return builder.build();
}

@Override
public Symbol enumShape(EnumShape shape) {
return getSymbolBuilder(shape)
.definitionFile(getDefinitionFile(serviceShape, shape))
.build();
}

@Override
public Symbol intEnumShape(IntEnumShape shape) {
return getSymbolBuilder(shape)
.definitionFile(getDefinitionFile(serviceShape, shape))
.build();
}

@Override
public Symbol memberShape(MemberShape shape) {
var builder = getSymbolBuilder(shape)
Expand Down
27 changes: 23 additions & 4 deletions ...gen-core/src/main/java/software/amazon/smithy/docgen/core/generators/MemberGenerator.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import software.amazon.smithy.model.shapes.StructureShape;
import software.amazon.smithy.model.shapes.TimestampShape;
import software.amazon.smithy.model.shapes.UnionShape;
import software.amazon.smithy.model.traits.EnumValueTrait;
import software.amazon.smithy.utils.SmithyUnstableApi;

/**
Expand Down Expand Up @@ -99,7 +100,7 @@ public void run() {

var symbol = context.symbolProvider().toSymbol(member);
var target = context.model().expectShape(member.getTarget());
writer.openMemberEntry(symbol, w -> target.accept(new MemberTypeVisitor(w, context)));
writer.openMemberEntry(symbol, w -> target.accept(new MemberTypeVisitor(w, context, member)));
writer.writeShapeDocs(member, context.model());

writer.closeMemberEntry();
Expand Down Expand Up @@ -140,7 +141,14 @@ public enum MemberListingType {
/**
* Indicates the listing is for an operation's output members.
*/
OUTPUT("Response Members");
OUTPUT("Response Members"),

/**
* Indicates the listing is for enums, intEnums, or unions, which each only
* allow one of their members to be selected.
*
*/
OPTIONS("Options");

private final String title;
private final String linkIdSuffix;
Expand Down Expand Up @@ -170,10 +178,12 @@ private static class MemberTypeVisitor extends ShapeVisitor.Default<Void> {

private final DocWriter writer;
private final DocGenerationContext context;
private final MemberShape member;

MemberTypeVisitor(DocWriter writer, DocGenerationContext context) {
MemberTypeVisitor(DocWriter writer, DocGenerationContext context, MemberShape member) {
this.writer = writer;
this.context = context;
this.member = member;
}

@Override
Expand Down Expand Up @@ -292,7 +302,16 @@ public Void mapShape(MapShape shape) {

@Override
public Void structureShape(StructureShape shape) {
writeShapeName(shape);
if (member.hasTrait(EnumValueTrait.class)) {
var trait = member.expectTrait(EnumValueTrait.class);
if (trait.getIntValue().isPresent()) {
writer.writeInline("$L", trait.expectIntValue());
} else {
writer.writeInline("$S", trait.expectStringValue());
}
} else {
writeShapeName(shape);
}
return null;
}

Expand Down
3 changes: 2 additions & 1 deletion smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,8 @@ public DocWriter closeHeading() {
*
* @param memberSymbol A symbol representing the member being documented.
* @param writeType A consumer that writes the type, including links to any referenced
* shapes.
* shapes. If the member is an enum member, it will write the literal
* value.
* @return returns the writer.
*/
public abstract DocWriter openMemberEntry(Symbol memberSymbol, Consumer<DocWriter> writeType);
Expand Down
13 changes: 12 additions & 1 deletion ...-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@
import software.amazon.smithy.codegen.core.Symbol;
import software.amazon.smithy.codegen.core.SymbolReference;
import software.amazon.smithy.codegen.core.SymbolWriter;
import software.amazon.smithy.docgen.core.DocSymbolProvider;
import software.amazon.smithy.model.shapes.MemberShape;
import software.amazon.smithy.model.traits.EnumValueTrait;
import software.amazon.smithy.utils.Pair;
import software.amazon.smithy.utils.SmithyUnstableApi;
import software.amazon.smithy.utils.StringUtils;
Expand Down Expand Up @@ -122,7 +125,15 @@ public DocWriter closeMemberListing() {
@Override
public DocWriter openMemberEntry(Symbol memberSymbol, Consumer<DocWriter> writeType) {
openListItem(ListType.UNORDERED);
writeInline("**$L** (*$C*): ", memberSymbol.getName(), writeType);
var member = memberSymbol.expectProperty(DocSymbolProvider.SHAPE_PROPERTY, MemberShape.class);
if (member.hasTrait(EnumValueTrait.class)) {
// The type written here will be the literal for enum values. Using
// backticks is standard for markdown literals, and it gives some
// differentiation between them and normal shape members.
writeInline("**$L** (`$C`): ", memberSymbol.getName(), writeType);
} else {
writeInline("**$L** (*$C*): ", memberSymbol.getName(), writeType);
}
return this;
}

Expand Down
19 changes: 16 additions & 3 deletions ...n-core/src/main/java/software/amazon/smithy/docgen/core/writers/SphinxMarkdownWriter.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@
import software.amazon.smithy.codegen.core.Symbol;
import software.amazon.smithy.codegen.core.SymbolWriter;
import software.amazon.smithy.docgen.core.DocSymbolProvider;
import software.amazon.smithy.model.shapes.MemberShape;
import software.amazon.smithy.model.traits.EnumValueTrait;
import software.amazon.smithy.utils.SmithyUnstableApi;

/**
Expand Down Expand Up @@ -49,10 +51,21 @@ public DocWriter openMemberEntry(Symbol memberSymbol, Consumer<DocWriter> writeT
memberSymbol.getProperty(DocSymbolProvider.LINK_ID_PROPERTY, String.class).ifPresent(linkId -> {
write("($L)=", linkId);
});
var member = memberSymbol.expectProperty(DocSymbolProvider.SHAPE_PROPERTY, MemberShape.class);

// Writes the members as a definition list
writeInline("""
$L: $C
:\s""", memberSymbol.getName(), writeType);
if (member.hasTrait(EnumValueTrait.class)) {
// The type written here will be the literal for enum values. Using
// backticks is standard for markdown literals, and it gives some
// differentiation between them and normal shape members.
writeInline("""
**$L**: `$C`
:\s""", memberSymbol.getName(), writeType);
} else {
writeInline("""
**$L**: $C
:\s""", memberSymbol.getName(), writeType);
}
indent();
return this;
}
Expand Down
18 changes: 18 additions & 0 deletions smithy-docgen-test/model/main.smithy
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,9 @@ structure DocumentedStructure {
// pull the docs from the target shape.
enum: DocumentedStringEnum

// This also will pull docs from the shape.
intEnum: DocumentedIntEnum

undocumented: UndocumentedStructure

/// This is a self-referential member. This is a thing that should be possible.
Expand All @@ -90,6 +93,21 @@ enum DocumentedStringEnum {
BAR
}

/// This in an enum that can have one of the following values:
///
/// - `SPAM`: `1`
/// - `EGGS`: `2`
///
/// Like other shapes in the model, this doesn't actually mean anything.
intEnum DocumentedIntEnum {
/// The spam and eggs placeholders are really only common in Python code bases.
SPAM = 1

/// They're a reference to a famous Monty Python skit, which is fitting because the
/// language itself is named after Monty Python.
EGGS = 2
}

// This structure has no docs anywhere
structure UndocumentedStructure {
blob: Blob
Expand Down

0 comments on commit afb1c42

Please sign in to comment.