Thoughts on writing macros documentation and examples project for GSoC'24

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 ( - 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:

  1. Writing XCTest unit tests as part of the development process, adhering to the well-known red-green-blue cycle in TDD.
  2. 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.

Hey @rubecdt,

It's great to see your interest in the project. Let's jump directly into the discussion.

Absolutely, the existing examples are quite solid. They just need a bit of polishing to really stand out.

This is a fantastic idea, though it's ambitious considering the scope of documentation required. Nevertheless, it's definitely worth attempting. Expanding our documentation to include both articles and tutorials could greatly enhance the accessibility and understanding of macros.

Integrating more complex examples to reflect real-world scenarios is indeed a goal for the project.

Dividing the tutorials to cover different aspects is a thoughtful approach. Whether these should be sections within each tutorial or separate tutorials altogether is a detail we can refine as we delve deeper into the project.

The second approach, incorporating all aspects into each tutorial, also appeals to me. It offers a comprehensive guide on specific macros in a single place, enhancing the learning experience. However, this aspect of the project is still open for discussion.

Your emphasis on documentation is commendable and crucial to the project's success. However, please keep in mind that a significant portion of this project involves coding and the creative process of ideating new macros. Your input and creativity in proposing new macros will be essential.