Repository: smithy-lang/smithy
Pull request #2389 (2024-08-29 20:51:56)

Fix small typos and grammatical errors in the full-stack-tutorial
#### Background
- Fixes typos, spelling mistakes, and grammatical errors in the tutorial

---
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.



Patch:
diff --git a/.github/workflows/make-docs.yml b/.github/workflows/make-docs.yml
index 3a4d003ec..ee9c912d3 100644
--- a/.github/workflows/make-docs.yml
+++ b/.github/workflows/make-docs.yml
@@ -80,7 +80,7 @@ jobs:
       run: |
         git pull
         rm -r 1.0/ 2.0/
-        mv /tmp/smithy-docs/* .
+        cp -R /tmp/smithy-docs/* .
         git config --global user.name "smithy-automation"
         git config --global user.email "github-smithy-automation@amazon.com"
         git add -A
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f08640a16..97c67a2c1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@
 ### Bug Fixes
 
 * Fixed formatting of `resource` shape `identifiers` and `properties` fields. ([#2377](https://github.com/smithy-lang/smithy/pull/2377))
+* Fixed issue with parsing different types of documentation comments. ([#2390](https://github.com/smithy-lang/smithy/pull/2390))
 * Fixed issue that would cause shape conflicts when loading the same model twice that uses `apply` on a member from a
   mixin. ([#2378](https://github.com/smithy-lang/smithy/pull/2378))
 * Fixed issue with generating CFN resource schema handler permissions for `@noReplace` resources. ([#2383](https://github.com/smithy-lang/smithy/pull/2383))
@@ -25,6 +26,7 @@
 
 ### Documentation
 
+* Added full-stack application tutorial. ([#2362](https://github.com/smithy-lang/smithy/pull/2362))
 * Added documentation to several places in the `smithy-aws-endpoints` trait definitions. ([#2374](https://github.com/smithy-lang/smithy/pull/2374))
 * Added note on `smithy-build.json` supporting `//` based comments. ([#2375](https://github.com/smithy-lang/smithy/pull/2375))
 * Clarified documentation for resolving auth schemes from endpoint rule sets. ([#2382](https://github.com/smithy-lang/smithy/pull/2382))
diff --git a/docs/source-2.0/tutorials/full-stack-tutorial.rst b/docs/source-2.0/tutorials/full-stack-tutorial.rst
index e20465143..7586a3e36 100644
--- a/docs/source-2.0/tutorials/full-stack-tutorial.rst
+++ b/docs/source-2.0/tutorials/full-stack-tutorial.rst
@@ -136,7 +136,7 @@ of coffee-related structures:
 
     namespace com.example
 
-    /// A enum describing the types of coffees available
+    /// An enum describing the types of coffees available
     enum CoffeeType {
         DRIP
         POUR_OVER
@@ -417,7 +417,7 @@ Run the build:
 
     smithy build
 
-The build will should fail for the following reason:
+The build should fail for the following reason:
 
 .. code-block:: text
     :caption: ``failure message``
diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlInternalTokenizer.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlInternalTokenizer.java
index d30fe637b..786f5dba6 100644
--- a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlInternalTokenizer.java
+++ b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlInternalTokenizer.java
@@ -149,7 +149,7 @@ final class IdlInternalTokenizer extends DefaultTokenizer {
         }
     }
 
-    private void clearDocCommentLinesForBr() {
+    void clearDocCommentLinesForBr() {
         if (!docCommentLines.isEmpty()) {
             validationEventListener.accept(LoaderUtils.emitBadDocComment(getCurrentTokenLocation(),
                                                                          removePendingDocCommentLines()));
diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlModelLoader.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlModelLoader.java
index 562c07e8a..81fbda08e 100644
--- a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlModelLoader.java
+++ b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlModelLoader.java
@@ -448,7 +448,7 @@ final class IdlModelLoader {
             try {
                 tokenizer.skipWsAndDocs();
                 String docLines = tokenizer.removePendingDocCommentLines();
-                List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this);
+                List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this, false);
                 if (docLines != null) {
                     traits.add(new IdlTraitParser.Result(DocumentationTrait.ID.toString(),
                                                          new StringNode(docLines, possibleDocCommentLocation),
@@ -467,7 +467,7 @@ final class IdlModelLoader {
         while (tokenizer.hasNext()) {
             try {
                 boolean hasDocComment = tokenizer.getCurrentToken() == IdlToken.DOC_COMMENT;
-                List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this);
+                List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this, false);
                 if (parseShapeDefinition(traits, hasDocComment)) {
                     parseShapeOrApply(traits);
                 }
@@ -672,7 +672,7 @@ final class IdlModelLoader {
 
         while (tokenizer.getCurrentToken() != IdlToken.EOF && tokenizer.getCurrentToken() != IdlToken.RBRACE) {
             List<IdlTraitParser.Result> memberTraits = IdlTraitParser
-                    .parseDocsAndTraitsBeforeShape(this);
+                    .parseDocsAndTraitsBeforeShape(this, true);
             SourceLocation memberLocation = tokenizer.getCurrentTokenLocation();
             tokenizer.expect(IdlToken.IDENTIFIER);
             String memberName = internString(tokenizer.getCurrentTokenLexeme());
@@ -723,6 +723,9 @@ final class IdlModelLoader {
         Set<String> definedMembers = new HashSet<>();
 
         tokenizer.skipWsAndDocs();
+        // Clear out any doc comments between the shape type or
+        // identifier and the opening LBRACE token.
+        tokenizer.clearDocCommentLinesForBr();
         tokenizer.expect(IdlToken.LBRACE);
         tokenizer.next();
         tokenizer.skipWs();
@@ -740,7 +743,7 @@ final class IdlModelLoader {
         ShapeId parent = operation.toShapeId();
 
         // Parse optional member traits.
-        List<IdlTraitParser.Result> memberTraits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this);
+        List<IdlTraitParser.Result> memberTraits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this, true);
         SourceLocation memberLocation = tokenizer.getCurrentTokenLocation();
 
         // Handle the case of a dangling documentation comment followed by "}".
@@ -988,7 +991,7 @@ final class IdlModelLoader {
     }
 
     private ShapeId parseInlineStructure(String name, IdlTraitParser.Result defaultTrait) {
-        List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this);
+        List<IdlTraitParser.Result> traits = IdlTraitParser.parseDocsAndTraitsBeforeShape(this, true);
         if (defaultTrait != null) {
             traits.add(defaultTrait);
         }
diff --git a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlTraitParser.java b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlTraitParser.java
index 82b52de57..90aabfa3a 100644
--- a/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlTraitParser.java
+++ b/smithy-model/src/main/java/software/amazon/smithy/model/loader/IdlTraitParser.java
@@ -69,7 +69,7 @@ final class IdlTraitParser {
      * @param loader IDL parser.
      * @return Return the parsed traits.
      */
-    static List<Result> parseDocsAndTraitsBeforeShape(IdlModelLoader loader) {
+    static List<Result> parseDocsAndTraitsBeforeShape(IdlModelLoader loader, boolean isParsingMember) {
         IdlInternalTokenizer tokenizer = loader.getTokenizer();
         tokenizer.skipWs();
 
@@ -91,6 +91,12 @@ final class IdlTraitParser {
             traits.add(docComment);
         }
         tokenizer.skipWsAndDocs();
+        // If there's a doc comment between traits and their target member,
+        // clear them so they're not prepended to a doc comment on the next
+        // member shape.
+        if (isParsingMember) {
+            tokenizer.clearDocCommentLinesForBr();
+        }
 
         return traits;
     }


Test patch:
diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/loader/detects-invalid-documentation-comments.errors b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/loader/detects-invalid-documentation-comments.errors
index 56aced838..978716049 100644
--- a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/loader/detects-invalid-documentation-comments.errors
+++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/loader/detects-invalid-documentation-comments.errors
@@ -1,7 +1,9 @@
 [WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 1 (before control) | Model.BadDocumentationComment
 [WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 2 (before namespace) | Model.BadDocumentationComment
 [WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 3 (before use) | Model.BadDocumentationComment
-[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 4 (inside trait)\nInvalid 5 (not before traits)\nValid docs for Foo | Model.BadDocumentationComment
-[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 6 (not before traits)\nInvalid 7 (inside shape line)\nInvalid 8 (dangling) | Model.BadDocumentationComment
-[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 9 (not before traits)\nInvalid 10 (dangling) | Model.BadDocumentationComment
+[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 4 (inside trait)\nInvalid 5 (not before traits) | Model.BadDocumentationComment
+[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 6 (not before traits)\nInvalid 7 (inside shape line) | Model.BadDocumentationComment
+[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 8 (dangling) | Model.BadDocumentationComment
+[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 9 (not before traits) | Model.BadDocumentationComment
+[WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 10 (dangling) | Model.BadDocumentationComment
 [WARNING] -: Found documentation comments ('///') attached to nothing. Documentation comments must appear on their own lines, directly before shapes and members, and before any traits. The invalid comments were: Invalid 11 (dangling) | Model.BadDocumentationComment
diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.json b/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.json
index ea06639a0..fa4fc6697 100644
--- a/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.json
+++ b/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.json
@@ -30,6 +30,12 @@
                         "smithy.api#documentation": "Docs on another member!"
                     }
                 },
+                "boot": {
+                    "target": "smithy.api#String",
+                    "traits": {
+                        "smithy.api#documentation": "I'll only have this documentation."
+                    }
+                },
                 "bam": {
                     "target": "smithy.api#String"
                 }
diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.smithy b/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.smithy
index 2ded3aa19..3f96dc95c 100644
--- a/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.smithy
+++ b/smithy-model/src/test/resources/software/amazon/smithy/model/loader/valid/doc-comments/doc-comments.smithy
@@ -29,6 +29,9 @@ structure MyStructure {
     /// IMPORTANT: These docs are ignored since they come after traits!
     baz: String,
 
+    /// I'll only have this documentation.
+    boot: String
+
     // no docs.
     bam: String,
 }