Skip to content

Commit

Permalink
private/model/api: Improve field and waiter doc strings (#879)
Browse files Browse the repository at this point in the history 
* private/model/api: Improve field and waiter doc strings

Adds doc strigns to waiters functions, and adds documenting when a field
in a struct is required.

* Regenerated service client for doc updates
  • Loading branch information
@jasdel
jasdel authored Oct 7, 2016
1 parent 810d747 commit c0d7d32
Show file tree
Hide file tree
Showing 98 changed files with 14,822 additions and 2,988 deletions.
21 changes: 16 additions & 5 deletions private/model/api/shape.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -420,10 +420,19 @@ type {{ .ShapeName }} struct {
{{ $context := . -}}
{{ range $_, $name := $context.MemberNames -}}
{{ $elem := index $context.MemberRefs $name }}
{{ $isRequired := $context.IsRequired $name }}
{{ $elem.Docstring }}
{{ $elem := index $context.MemberRefs $name -}}
{{ $isRequired := $context.IsRequired $name -}}
{{ $doc := $elem.Docstring -}}
{{ $doc }}
{{ if $isRequired -}}
{{ if $doc -}}
//
{{ end -}}
// {{ $name }} is a required field
{{ end -}}
{{ $name }} {{ $context.GoStructType $name $elem }} {{ $elem.GoTags false $isRequired }}
{{ end }}
}
{{ if not .API.NoStringerMethods }}
Expand All @@ -441,8 +450,10 @@ var enumShapeTmpl = template.Must(template.New("EnumShape").Parse(`
const (
{{ $context := . -}}
{{ range $index, $elem := .Enum -}}
// @enum {{ $context.ShapeName }}
{{ index $context.EnumConsts $index }} = "{{ $elem }}"
{{ $name := index $context.EnumConsts $index -}}
// {{ $name }} is a {{ $context.ShapeName }} enum value
{{ $name }} = "{{ $elem }}"
{{ end }}
)
`))
Expand Down
21 changes: 15 additions & 6 deletions private/model/api/waiters.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,16 @@ func (a *WaitAcceptor) ExpectedString() string {
}
}

var tplWaiter = template.Must(template.New("waiter").Parse(`
var waiterTmpls = template.Must(template.New("waiterTmpls").Parse(`
{{ define "docstring" -}}
// WaitUntil{{ .Name }} uses the {{ .Operation.API.NiceName }} API operation
// {{ .OperationName }} to wait for a condition to be met before returning.
// If the condition is not meet within the max attempt window an error will
// be returned.
{{- end }}
{{ define "waiter" }}
{{ template "docstring" . }}
func (c *{{ .Operation.API.StructName }}) WaitUntil{{ .Name }}(input {{ .Operation.InputRef.GoType }}) error {
waiterCfg := waiter.Config{
Operation: "{{ .OperationName }}",
Expand All @@ -121,18 +130,18 @@ func (c *{{ .Operation.API.StructName }}) WaitUntil{{ .Name }}(input {{ .Operati
}
return w.Wait()
}
`))
{{- end }}
var tplWaiterIface = template.Must(template.New("waiteriface").Parse(`
{{ define "waiter interface" }}
WaitUntil{{ .Name }}({{ .Operation.InputRef.GoTypeWithPkgName }}) error
{{- end }}
`))

// InterfaceSignature returns a string representing the Waiter's interface
// function signature.
func (w *Waiter) InterfaceSignature() string {
var buf bytes.Buffer
err := tplWaiterIface.Execute(&buf, w)
if err != nil {
if err := waiterTmpls.ExecuteTemplate(&buf, "waiter interface", w); err != nil {
panic(err)
}

Expand All @@ -142,7 +151,7 @@ func (w *Waiter) InterfaceSignature() string {
// GoCode returns the generated Go code for an individual waiter.
func (w *Waiter) GoCode() string {
var buf bytes.Buffer
if err := tplWaiter.Execute(&buf, w); err != nil {
if err := waiterTmpls.ExecuteTemplate(&buf, "waiter", w); err != nil {
panic(err)
}

Expand Down
2 changes: 2 additions & 0 deletions private/protocol/restjson/build_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1206,6 +1206,7 @@ type InputService10TestShapeInputService10TestCaseOperation1Input struct {

Checksum *string `location:"header" locationName:"x-amz-sha256-tree-hash" type:"string"`

// VaultName is a required field
VaultName *string `location:"uri" locationName:"vaultName" type:"string" required:"true"`
}

Expand Down Expand Up @@ -1335,6 +1336,7 @@ type InputService11TestShapeInputService11TestCaseOperation1Input struct {
// Bar is automatically base64 encoded/decoded by the SDK.
Bar []byte `type:"blob"`

// Foo is a required field
Foo *string `location:"uri" locationName:"Foo" type:"string" required:"true"`
}

Expand Down
100 changes: 76 additions & 24 deletions service/acm/api.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -556,9 +556,13 @@ type AddTagsToCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`

// The key-value pair that defines the tag. The tag value is optional.
//
// Tags is a required field
Tags []*Tag `min:"1" type:"list" required:"true"`
}

Expand Down Expand Up @@ -741,6 +745,8 @@ type DeleteCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`
}

Expand Down Expand Up @@ -793,6 +799,8 @@ type DescribeCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`
}

Expand Down Expand Up @@ -846,6 +854,8 @@ type DomainValidation struct {
_ struct{} `type:"structure"`

// Fully Qualified Domain Name (FQDN) of the form www.example.com or example.com.
//
// DomainName is a required field
DomainName *string `min:"1" type:"string" required:"true"`

// The base validation domain that acts as the suffix of the email addresses
Expand All @@ -871,6 +881,8 @@ type DomainValidationOption struct {
_ struct{} `type:"structure"`

// Fully Qualified Domain Name (FQDN) of the certificate being requested.
//
// DomainName is a required field
DomainName *string `min:"1" type:"string" required:"true"`

// The domain to which validation email is sent. This is the base validation
Expand All @@ -890,6 +902,8 @@ type DomainValidationOption struct {
// postmaster@subdomain.example.com
//
// webmaster@subdomain.example.com
//
// ValidationDomain is a required field
ValidationDomain *string `min:"1" type:"string" required:"true"`
}

Expand Down Expand Up @@ -934,6 +948,8 @@ type GetCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`
}

Expand Down Expand Up @@ -1060,6 +1076,8 @@ type ListTagsForCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`
}

Expand Down Expand Up @@ -1116,9 +1134,13 @@ type RemoveTagsFromCertificateInput struct {
//
// For more information about ARNs, see Amazon Resource Names (ARNs) and AWS
// Service Namespaces (http://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html).
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`

// The key-value pair that defines the tag to remove.
//
// Tags is a required field
Tags []*Tag `min:"1" type:"list" required:"true"`
}

Expand Down Expand Up @@ -1185,6 +1207,8 @@ type RequestCertificateInput struct {
// you want to secure with an ACM Certificate. Use an asterisk (*) to create
// a wildcard certificate that protects several sites in the same domain. For
// example, *.example.com protects www.example.com, site.example.com, and images.example.com.
//
// DomainName is a required field
DomainName *string `min:"1" type:"string" required:"true"`

// The base validation domain that will act as the suffix of the email addresses
Expand Down Expand Up @@ -1296,10 +1320,14 @@ type ResendValidationEmailInput struct {
// The ARN must be of the form:
//
// arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012
//
// CertificateArn is a required field
CertificateArn *string `min:"20" type:"string" required:"true"`

// The Fully Qualified Domain Name (FQDN) of the certificate that needs to be
// validated.
//
// Domain is a required field
Domain *string `min:"1" type:"string" required:"true"`

// The base validation domain that will act as the suffix of the email addresses
Expand All @@ -1318,6 +1346,8 @@ type ResendValidationEmailInput struct {
// postmaster@subdomain.example.com
//
// webmaster@subdomain.example.com
//
// ValidationDomain is a required field
ValidationDomain *string `min:"1" type:"string" required:"true"`
}

Expand Down Expand Up @@ -1378,6 +1408,8 @@ type Tag struct {
_ struct{} `type:"structure"`

// The key of the tag.
//
// Key is a required field
Key *string `min:"1" type:"string" required:"true"`

// The value of the tag.
Expand Down Expand Up @@ -1411,61 +1443,81 @@ func (s *Tag) Validate() error {
}

const (
// @enum CertificateStatus
// CertificateStatusPendingValidation is a CertificateStatus enum value
CertificateStatusPendingValidation = "PENDING_VALIDATION"
// @enum CertificateStatus

// CertificateStatusIssued is a CertificateStatus enum value
CertificateStatusIssued = "ISSUED"
// @enum CertificateStatus

// CertificateStatusInactive is a CertificateStatus enum value
CertificateStatusInactive = "INACTIVE"
// @enum CertificateStatus

// CertificateStatusExpired is a CertificateStatus enum value
CertificateStatusExpired = "EXPIRED"
// @enum CertificateStatus

// CertificateStatusValidationTimedOut is a CertificateStatus enum value
CertificateStatusValidationTimedOut = "VALIDATION_TIMED_OUT"
// @enum CertificateStatus

// CertificateStatusRevoked is a CertificateStatus enum value
CertificateStatusRevoked = "REVOKED"
// @enum CertificateStatus

// CertificateStatusFailed is a CertificateStatus enum value
CertificateStatusFailed = "FAILED"
)

const (
// @enum FailureReason
// FailureReasonNoAvailableContacts is a FailureReason enum value
FailureReasonNoAvailableContacts = "NO_AVAILABLE_CONTACTS"
// @enum FailureReason

// FailureReasonAdditionalVerificationRequired is a FailureReason enum value
FailureReasonAdditionalVerificationRequired = "ADDITIONAL_VERIFICATION_REQUIRED"
// @enum FailureReason

// FailureReasonDomainNotAllowed is a FailureReason enum value
FailureReasonDomainNotAllowed = "DOMAIN_NOT_ALLOWED"
// @enum FailureReason

// FailureReasonInvalidPublicDomain is a FailureReason enum value
FailureReasonInvalidPublicDomain = "INVALID_PUBLIC_DOMAIN"
// @enum FailureReason

// FailureReasonOther is a FailureReason enum value
FailureReasonOther = "OTHER"
)

const (
// @enum KeyAlgorithm
// KeyAlgorithmRsa2048 is a KeyAlgorithm enum value
KeyAlgorithmRsa2048 = "RSA_2048"
// @enum KeyAlgorithm

// KeyAlgorithmEcPrime256v1 is a KeyAlgorithm enum value
KeyAlgorithmEcPrime256v1 = "EC_prime256v1"
)

const (
// @enum RevocationReason
// RevocationReasonUnspecified is a RevocationReason enum value
RevocationReasonUnspecified = "UNSPECIFIED"
// @enum RevocationReason

// RevocationReasonKeyCompromise is a RevocationReason enum value
RevocationReasonKeyCompromise = "KEY_COMPROMISE"
// @enum RevocationReason

// RevocationReasonCaCompromise is a RevocationReason enum value
RevocationReasonCaCompromise = "CA_COMPROMISE"
// @enum RevocationReason

// RevocationReasonAffiliationChanged is a RevocationReason enum value
RevocationReasonAffiliationChanged = "AFFILIATION_CHANGED"
// @enum RevocationReason

// RevocationReasonSuperceded is a RevocationReason enum value
RevocationReasonSuperceded = "SUPERCEDED"
// @enum RevocationReason

// RevocationReasonCessationOfOperation is a RevocationReason enum value
RevocationReasonCessationOfOperation = "CESSATION_OF_OPERATION"
// @enum RevocationReason

// RevocationReasonCertificateHold is a RevocationReason enum value
RevocationReasonCertificateHold = "CERTIFICATE_HOLD"
// @enum RevocationReason

// RevocationReasonRemoveFromCrl is a RevocationReason enum value
RevocationReasonRemoveFromCrl = "REMOVE_FROM_CRL"
// @enum RevocationReason

// RevocationReasonPrivilegeWithdrawn is a RevocationReason enum value
RevocationReasonPrivilegeWithdrawn = "PRIVILEGE_WITHDRAWN"
// @enum RevocationReason

// RevocationReasonAACompromise is a RevocationReason enum value
RevocationReasonAACompromise = "A_A_COMPROMISE"
)
Loading

0 comments on commit c0d7d32

Please sign in to comment.