Hello! Allow me to introduce myself on the Swift forums.
I was contemplating applying for GSoC when this topic caught my attention.
Herein, I present my approach to this project. I highly appreciate any corrections or suggestions to improve it. I would be particularly grateful in case potential mentors @ahoppen and @Matejkob could provide their insightst.
Starting with the basics, I believe the current examples in swift-syntax need minimal adjustments to illustrate the basic usage of each macro on its respective documentation page. Each macro type could be documented via an article, a concise tutorial, or both. Certainly, some could be swapped for examples that more closely mirror real-world scenarios. However, I don’t view this as an immediate priority, as the current examples sufficiently illustrate how to implement the macros, thereby fulfilling their fundamental role. The macro chapter in The Swift Programming Language will be our foundation for reasoning. This section of the book and the new documentation should be considered collectively, ensuring a cohesive fit.
Regarding the real-world examples expected as part of the DocC tutorial, I propose a single project that encompasses most, if not all, macros. Aiming to showcase their capabilities and integration, this seems to be the most effective approach.
After reviewing the project ideas page (Swift.org - Project Ideas for GSoC 2024), it appears coding is divided into three main tasks: implementation, diagnostics, and tests. I was torn between splitting the project into three separate tutorials covering each aspect (starting with implementation, followed by tests and diagnostics) or adopting a distribution that naturally follows the project's functionality and implementation. The latter approach would still maintain an internal division within each tutorial part as follows:
- Writing
XCTestunit tests as part of the development process, adhering to the well-known red-green-blue cycle in TDD. - Considering how to prevent misuse and provide rich, useful diagnostics to API users.
| Approach | Pros | Cons |
|---|---|---|
| Three separate tutorials: Writing Macros, Testing, Diagnostics. | Focuses on each aspect of crafting a quality macro. | - Risks of readers neglecting the testing and diagnostics tutorials. - Revisiting code for testing and diagnostics implementation is necessary. |
| Several tutorials: Covering functionalities, each divided into implementation-testing and diagnostics. | Mimics a real-world workflow, dividing coding in smaller tasks. | Might be more challenging to follow as it interweaves all steps simultaneously. |
I am now leaning towards selecting the second option, which involves covering all aspects in each tutorial.
I find myself with a question regarding the selection of the topic to drive the tutorial. I believe showcasing macro potential by reimplementing functionalities of a real-world existing API, simplifying where necessary to maintain focus, is a sound approach. The key is to balance the content to enable learners to grasp the full capabilities and applications of macros. So far, I’ve identified three potential tutorial topics:
- Test macros
- A macro-based API for creating and managing DTO models
- Observable macro reimplementation
The testing macro appeals to me the most due to its broad applicability, from command-line programs to servers and everything in between, such as app development. It also offers an excellent opportunity to emphasize the significance and benefits of testing in enhancing code quality and programming ergonomics.
I stumbled upon this project implementing a new testing library API using macros. Although still experimental, I see no issue here. My work could build on it. Even if the API undergoes significant revision, as might be expected with experimental projects, the examples in the tutorial will be crafted to remain relevant as demonstrations.