From 8babdc87ccfa6296e046475f280a7e17032eb3d4 Mon Sep 17 00:00:00 2001 From: Jordon Phillips Date: Fri, 24 Nov 2023 12:56:05 +0100 Subject: [PATCH] Rephrase auth trait documentation This rephrases the documentation for auth traits to read more like documentation for the auth type rather than documentation for a function. This allows it to be more naturally used in documentation generation without change. This also adds inline links to external documentation rather than solely relying on the external docs trait. While that trait is useful still, rendered docs are more natural if there's inline links too. --- .../src/main/resources/META-INF/smithy/aws.auth.smithy | 10 +++++----- .../software/amazon/smithy/model/loader/prelude.smithy | 9 +++------ 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.auth.smithy b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.auth.smithy index fcbb7e24ccc..7c67bb40491 100644 --- a/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.auth.smithy +++ b/smithy-aws-traits/src/main/resources/META-INF/smithy/aws.auth.smithy @@ -14,11 +14,11 @@ structure cognitoUserPools { providerArns: StringList } -/// Signature Version 4 is the process to add authentication information to -/// AWS requests sent by HTTP. For security, most requests to AWS must be -/// signed with an access key, which consists of an access key ID and secret -/// access key. These two keys are commonly referred to as your security -/// credentials. +/// [Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) +/// is the process to add authentication information to AWS requests sent by HTTP. For +/// security, most requests to AWS must be signed with an access key, which consists +/// of an access key ID and secret access key. These two keys are commonly referred to +/// as your security credentials. @authDefinition(traits: [unsignedPayload]) @externalDocumentation( Reference: "https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html" diff --git a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy index 007f60a90e0..947082d00c2 100644 --- a/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy +++ b/smithy-model/src/main/resources/software/amazon/smithy/model/loader/prelude.smithy @@ -246,8 +246,7 @@ structure authDefinition { traits: TraitShapeIdList } -/// Enables HTTP Basic Authentication as defined in RFC 2617 on a service -/// or operation. +/// HTTP Basic Authentication as defined in [RFC 2617](https://tools.ietf.org/html/rfc2617.html). @trait( selector: "service" breakingChanges: [ @@ -258,8 +257,7 @@ structure authDefinition { @externalDocumentation("RFC 2617": "https://tools.ietf.org/html/rfc2617.html") structure httpBasicAuth {} -/// Enables HTTP Digest Authentication as defined in RFC 2617 on a service -/// or operation. +/// HTTP Digest Authentication as defined in [RFC 2617](https://tools.ietf.org/html/rfc2617.html). @trait( selector: "service" breakingChanges: [ @@ -270,8 +268,7 @@ structure httpBasicAuth {} @externalDocumentation("RFC 2617": "https://tools.ietf.org/html/rfc2617.html") structure httpDigestAuth {} -/// Enables HTTP Bearer Authentication as defined in RFC 6750 on a service -/// or operation. +/// HTTP Bearer Authentication as defined in [RFC 6750](https://tools.ietf.org/html/rfc6750.html). @trait( selector: "service" breakingChanges: [