Annotations are simply small bits of metadata that annotate our properties functions, enums, enum cases and other types.

Then, later we can access this metadata inside our .stencil template files.

Let's try it out.

Before we begin, let's add a new Swift Enum to our project. Nothing special here so far, just regular Swift.

enumSpaceshipKind{casecruisercasefrieghtercasedestroyer}

Next, we'll add a new SpaceshipKind+Count.stencil file for Sourcery to render. We'll use the "Empty" option in Xcode when creating a new file, then open the Inspector (right side) and change the file's type to Swift Source so it will read (slightly) nicer in Xcode.

Finally, let's run sourcery:

sourcery source/ templates/ /source/_generated/ --watch --verbose

Passing in the --watch tells Sourcery to run continuously and re-render our templates anytime our code or templates change. Neat.

The --verbose flag tells Sourcery to print a bunch of useful debug info to the console while it's working. Helpful at first, but once we're more comfortable with Sourcery, we can probably leave this off.

There's a few ways we could approach this in Sourcery, but this gives us a nice way to learn about and understand how annotations work.

We'll add one above EngineKind in our code:

/// sourcery: skipCountenumEngineKind{casehyperdrivecasesunsail}

Annotations are simply special comments that Sourcery parses, and makes available in our .stencil templates.

The cool part is it's location aware, so we can put annotations above types, and they'll be available on those types in our .stencil templates! Same goes for annotations on properties, enum cases and more!