Address review comments and some minor changes

Author: lokesh-tr

_data/authors.yml

@@ -476,4 +476,4 @@ lokeshtr:
   name: Lokesh T. R.
   email: [email protected]
   github: lokesh-tr
-  about: "Lokesh T. R. is a Google Summer Of Code 2024 Student from Tamil Nadu, India, who worked on SourceKitLSP and the Swift Extension for Visual Studio Code. He has a wide range of interests including App & Web Development, Programming Languages & Developer Tools, AI & Machine Learning and many more."
+  about: "Lokesh T. R. is a Google Summer Of Code 2024 Student from Tamil Nadu, India, who worked on SourceKit-LSP and the Swift Extension for Visual Studio Code. He has a wide range of interests including App & Web Development, Programming Languages & Developer Tools, AI & Machine Learning and many more."

_posts/2030-12-28-expansion-of-swift-macros-in-vscode.md

@@ -35,9 +35,7 @@ And as a bonus, we also worked on supporting macro expansions in other LSP-based
 
 ### When can you start using this feature?
 
-This will be available with SourceKit-LSP bundled with Swift 6.1 and the corresponding VS Code Swift Extension Release.
-
-For the curious minds, This feature is available in the `main` branch of `sourcekit-lsp` and `vscode-swift` repositories, right now.
+This will be available with SourceKit-LSP bundled with **Swift 6.1 and the corresponding VS Code Swift Extension Release**. For the curious minds, This feature is available in the `main` branch of `sourcekit-lsp` and `vscode-swift` repositories, right now.
 
 ## Implementation Details
 
@@ -52,7 +50,7 @@ Let's have a look at three key components that you use in your everyday life in
    - communicates using Language Server Protocol (LSP)
 3. SourceKitD (Background Service):
    - provides the raw data and operations to SourceKit-LSP
-   - baked into the swift compiler
+   - shares implementation details with the Swift compiler
 
 ### Main Goal
 
@@ -92,98 +90,74 @@ export interface GetReferenceDocumentResult {
 ("sourcekit-lsp://swift-macro-expansion/LaCb-LcCd.swift?fromLine=&fromColumn=&toLine=&toColumn=&bufferName=&parent=");
 ```
 
-- `"workspace/peekDocuments"` allows the SourceKit-LSP Server to show the the contents stored in the `locations` inside the source file `uri` as a peek window
-- Reference Document URL Scheme `sourcekit-lsp://` so that we can use it to encode the necessary data required to generate any form of content to which the URL corresponds to.
-- We introduce the very first `document-type` of the Reference Document URL which is `swift-macro expansion`. This will encode all the necessary data required to generate the macro expansion contents.
-- `"workspace/getReferenceDocument"` is introduced so that the Editor Client can make a request to the SourceKit-LSP Server with the Reference Document URL to fetch its contents.
+#### Working of the "Expand Macro" Code Action
 
-The way this works is that, we generate the Reference Document URLs from the macro expansions generated using sourcekitd and make a `"workspace/peekDocuments"` request to the Editor Client. In VS Code, this executes the `"editor.action.peekLocations"` command to present a peeked editor.
+1. The `"workspace/peekDocuments"` request is sent from SourceKit-LSP to the editor and prompts it to show the the contents of `locations` inside the source file `uri` as a peek window at `position`. In VS Code, this executes the `"editor.action.peekLocations"` command to present a peeked editor.
+2. Since the contents of the macro expansion are not represented by a file on disk, we introduce a custom `sourcekit-lsp://` URL scheme to represent the macro expansion buffers. In the future, this URL scheme can be represented for other use cases such as generated interfaces by using a `document-type` other than `swift-macro-expansion`.  
+macro expansion contents.
+3. To fetch the contents of this custom URL scheme, the editor client sends a `"workspace/getReferenceDocument"` to SourceKit-LSP.
 
-![Working of PeekDocumentsRequest](/assets/images/expansion-of-swift-macros-in-vscode-blog/working-of-peekdocumentsrequest.jpeg)
+![Working of the Expand Macro Code Action](/assets/images/expansion-of-swift-macros-in-vscode-blog/working-of-getreferencedocumentrequest.jpeg)
 
-Since VS Code can't resolve the contents of Reference Document URL, it makes a `"workspace/getReferenceDocument"` request to the SourceKit-LSP Server, thereby retrieveing the contents and successfully displaying it in the peeked editor.
+### Stretch Goals
 
-![Working of GetReferenceDocumentRequest](/assets/images/expansion-of-swift-macros-in-vscode-blog/working-of-getreferencedocumentrequest.jpeg)
+#### Achieving Semantic Functionality (jump-to-definition, quick help on hover, syntax highlighting, etc.)
 
-### Stretch Goals
+   By default, SourceKit-LSP and SourceKitD are not equipped to handle our newly introduced Reference Document URLs. To enable semantic functionality, such as jump-to-definition, quick help on hover, and syntax highlighting, the build arguments of the file are required. To address this, we utilised the source file's build arguments and applied them to the reference documents. This effectively tricks sourcekitd into providing semantic functionality for these reference documents.
 
-1. Achieving Semantic Functionality (jump-to-definition, quick help on hover, syntax highlighting, etc.):
-   - SourceKit-LSP and SourceKitD by default doesn't know how to handle Reference Document URLs.
-   - The build arguments of a file is needed to provide semantic functionality.
-   - We used the source file's build arguments as build arguments of the reference documents to trick sourcekitd to provide Semantic Functionality for the reference documents.
-2. Achieving Nested Macro Expansion:
-   - Due to the flexible nature of the Reference Document URLs, nested macro expansions becomes trivial.
-   - The beauty of the Reference Document URLs is that we can nest the Reference Document URLs.
-   - We set the `parent` parameter of the macro expansion reference document URL to the source file if it's a first level macro expansion or to the reference document from which the macro expansion originates if it was second or third or n-th level macro expansion. This allows us to expand nested macros efficiently.
+#### Achieving Nested Macro Expansion
+
+   The flexible nature of Reference Document URLs simplifies the process of nested macro expansions. A key advantage of these URLs is their ability to allow nesting. To achieve nested macro expansion, we set the `parent` parameter of the macro expansion reference document URL to the source file if it represents a first-level macro expansion. For subsequent expansions, whether at the second, third, or n-th level, the `parent` parameter points to the reference document from which the macro expansion originates. This mechanism enables the efficient expansion of nested macros.
 
 ### Bonus
 
-While the new LSP Extensions which we introduced, doesn't work out-of-the-box in other LSP-based editors and requires the extension / plugin developers of respective editors to make use of it, We worked on providing a basic form of first level macro expansion support using the standard LSP Requests to support other LSP-based editors.
+While the new LSP extensions which we introduced, don't work out-of-the-box in other LSP-based editors and requires the extension / plugin developers of respective editors to make use of it, we worked on providing a basic form of first level macro expansion support using the standard LSP Requests to support other LSP-based editors.
 
 This works as follows:
 
-1. SourceKitLSP asks SourceKitD for macro expansions.
+1. SourceKit-LSP asks sourcekitd for macro expansions.
 2. It then stitches all the macro expansions together in a single file.
 3. It stores the file in some temporary location in the disk.
 4. It then makes a `ShowDocumentRequest` to open and show the file in the editor.
 
-That wraps up the GSoC project successfully!
-
-### What's left to do?
-
-- I will be working on implementing a test case that encompasses all the semantic features in all nested macro levels in sourcekit-lsp.
-- I will also implement some end-to-end test cases in the vscode-swift side which ensures that they really work as intended in a real world situation.
+## Conclusion
 
-Test cases for freestanding macros, attached macros and nested macros are already in place.
-Code Documentation is also in place for everything that we have implemented so far.
+That wraps up our Google Summer of Code project successfully! 🎉
 
 ### Future Directions
 
-1. Feedback, Feedback, Feedback!
+#### 1. Feedback, Feedback, Feedback
 
-   - We had put so much attention to detail and ensured that every decision made in the design process was thoughtful.
-   - But, you may have a better idea, or you may find some issues, and we would love to improve this feature.
-   - Please file an issue to suggest an idea or report bugs in the sourcekit-lsp or vscode-swift repository wherever you face the issue.
+   We put a great deal of attention to detail, ensuring that every decision in the design process was thoughtful and deliberate. However, we understand that you might have better ideas or come across issues we haven't anticipated, and we're always eager to improve this feature. If you have suggestions or encounter any bugs, we encourage you to file an issue in either the sourcekit-lsp or vscode-swift repository, depending on where you face the problem.
 
-2. Migrating the non-standard `"workspace/getReferenceDocument"` to the new standard `"workspace/textDocumentContent"` Request
+#### 2. Implementing Semantic Functionality and Nested Macro Expansions for all LSP-based editors
 
-   - We should be able to perform this migration when the specifications of LSP 3.18 gets finalised.
-   - With this, the custom request need not be handled by the extension / plugin developer of an LSP-based editor.
+   With LSP 3.18 nearing finalization, there should be focus on unifying how macro expansions and reference documents are handled across LSP-based editors to enable semantic functionality and nested macro expansions.
 
-3. Migrate from generating temporary files in the Disk to Reference Document URLs for other LSP-based editors
+   One of the key steps in this process is migrating from the custom `"workspace/getReferenceDocument"` request to the upcoming standardized `"workspace/textDocumentContent"` request. This will simplify the integration, removing the need for extension / plugin developers to handle custom requests and aligning with LSP specifications. Additionally, once LSP 3.18 is implemented, we can eliminate the reliance on temporary file storage by replacing it with the generated on-the-fly Reference Document URLs.
 
-   - We are currently unable to generate macro expansions on-the-fly in other LSP-based editors since we don't have our LSP Extension for getting the contents of the reference document.
-   - Building on top of the previous idea, when LSP 3.18 gets finalised, we should be able to completely eliminate temporary file storage in favour of the standard `"workspace/textDocumentContent"` Request.
+   A significant challenge will involve handling positional shifts in line and character numbers caused by macro expansions. When macros expand, they often change the layout of the file, causing subsequent macros to shift from their original positions. Implementing semantic functionality and nested macro expansions in macro expansion documents for all LSP-based editors should account for these shifts, ensuring that editors can accurately track and display the correct positions of expanded macros. This adjustment is crucial to providing smooth, error-free navigation and proper context across all LSP-based editors.
 
-4. Adding Semantic Functionality & Nested Macro Expansion support for other LSP-based editors
+#### 3. Other Use Cases for the Reference Document URL
 
-   - This is tricky to implement since the temporary file (or reference document after LSP 3.18) will have all the macro expansions of a given macro in a single file.
-   - Although the same approach can be used such as passing the source file's build arguments and `parent` to be the macro's originating file, there will be line and character position shifts that should be taken into consideration.
-   - For example, the third macro expansion of a given attached macro will be expected to start at `0:0` but its actual location will be shifted by the first and second macro expansion's content length and three lines of comments that describes where the macro will be present in the original file
+   Reference Document URLs were built from the ground up to encode the data necessary to display any form of content. This functionality allows anyone to present any content of their choice, whether in a peeked editor or a fully open document, as long as it is generated during compile time. One such example we discussed today is the `swift-macro-expansion` document type.
 
-5. Other Use Cases for the Reference Document URL
+   Also, For instance, we can migrate `OpenInterfaceRequest` to Reference Document URLs to display the generated `.swiftinterface` files of modules. Additionally, we can show implicitly generated constructors and synthesized code related to `Equatable`, `Hashable`, and `Codable` conformances. Another use case involves previewing or rendering generated HTML from the Mustache template engine by integrating its CLI.
 
-   - Reference Document URLs where built from the ground up to allow for encoding the data required to show any form of content, one such example which we discussed today is `swift-macro-expansion` document type.
-   - This should allow anyone to show any content of their choice, in a peeked editor or a fully open document, as long as its generated during compile time.
-   - The following use cases are not related to macro expansions but uses the Reference Document URL that we created to show other document types:
-     - Migrating `OpenInterfaceRequest` to Reference Document URLs to show Swift Generated Interfaces
-     - Showing Implicitly generated constructors and Synthesized code upon `Equatable`, `Hashable` and `Codable` Conformances.
-     - Showing a preview of generated HTML or rendering the generated HTML from the Mustache template engine by hooking up its CLI.
-   - These are just few examples, and the fact that you can show various document formats based on various code generation behaviours brings a wide range of possibilities, and hence, you can bring your own idea.
-   - And with LSP 3.18, this will be standardised across all editors, not just VS Code.
+   These are just a few examples. The ability to present various document formats based on different code generation behaviors opens up a wide range of possibilities, encouraging you to bring your own ideas to life. With LSP 3.18, this functionality will be standardized across all editors, not just VS Code.
 
-## Thanks & Gratitude
+### Thanks & Gratitude
 
 I offer my deepest gratitude to my mentors, Alex Hoppen (@ahoppen) and Adam Fowler (@adam-fowler) without whom this journey is impossible. Google Summer of Code is not only the work of myself as a contributor but also the work of my mentors in guiding me and helping me out whenever possible.
 
 Thanks to you both for accepting my project proposal, spending hours setting up my environment, getting me started with PRs, your wonderful ideas and feedback on my ideas, attending the weekly meetings, allowing me to be flexible, detailed PR reviews, giving me directions and all the immediate and quick responses. I hope I gave you both a wonderful GSoC experience.
 
-If not for you two people, this project wouldn't be a success.
+If not for you two people, this project wouldn't be a success. 💖
 
-### Special Thanks
+#### Special Thanks ❤️
 
 - Thanks to Fredrik Wieczerkowski (@fwcd) for his initial proof-of-concept on Expansion of Swift Macros in Visual Studio Code and also for his Pull Request that migrates `workspace/getReferenceDocument` to the upcoming `workspace/textDocumentContent`.
 - Thanks to Paul LeMarquand (@plemarquand) for testing out my project in its very early stages.
 - Thanks to Douglas Gregor (@douglas_gregor) and Rintaro Ishizaki (@rintaro) for coming up with their own use cases with the generic LSP Requests that also laid the foundation for macro expansions.
 - Thanks to Mateusz Bąk (@Matejkob) and Paris Pittman (@parispittman) for fueling me with positivity to present my project wherever possible.
-- Thanks to the entire Swift Community always being so welcoming and supportive.
+- Thanks to the entire Swift Community for always being so welcoming and supportive.