# \[Pitch\] Swift Snippets

**URL:** <https://forums.swift.org/t/pitch-swift-snippets/56348>\
**Category:** Pitches\
**Tags:** documentation, packagemanager, docc, snippets\
**Created:** [March 30, 2022, 6:01pm UTC](https://forums.swift.org/t/pitch-swift-snippets/56348 "2022-03-30T18:01:13Z")\
**Posts on this page:** 1\
**Showing post:** 34

<div class="post-metadata">

**Author:** ![bitjammer](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/bitjammer/32/18612_2.png) [@bitjammer](https://forums.swift.org/u/bitjammer)\
**Post date:** [March 31, 2022, 7:22pm UTC](https://forums.swift.org/t/pitch-swift-snippets/56348/34 "2022-03-31T19:22:49Z")

</div>

> [@franklin](#):
>
> I'd be interested in hearing more of your rationale for the one-to-one mapping between snippets and files. Do you see a use case where you'd want to define multiple related small snippets in a file to showcase different aspects of my library's API. Looking at [this](https://apple.github.io/swift-markdown/documentation/markdown/parsing-building-and-modifying-markup-trees) documentation page for Swift-Markdown, it contains docs for three related concepts, so I might expect being able to declare these three snippets in the same file.

So, when I look at that documentation, I see three related concepts but they don't always go together. For example, I can parse a Markdown file, format it, and not do any modification. Someone may want to build up some Markdown from structured data and then print it out, so no parsing needs to be done. I don't think I would have combined those concepts into one article if I were writing that documentation, unless I were putting everything about the library on one page. I'm wondering if that article was basically pulled from the repo's README? I think when I wrote the README, it was basically just a "here's everything, I guess" article (which READMEs tend to be).

The goal of snippets is one block of code is one high-level task. Putting that in one file means that an author or a reader doesn't have to do the extra work to sort a growing wall of text, which starts to get back into one of the problems with sample code projects.

If sharing _demo code_ (code that executes but is not shown) among snippets becomes an issue, a package can define a helper library. If sharing _presentation code_ (the code that is actually shown in the rendered code block) becomes an issue, I think that perhaps indicates a potential need for an API. That is another benefit that I see for shorter example code–it highlights the usability (or lack thereof) of libraries very well, so I expect that the more that folks write snippets, the more informed they will be about the design of their API.

> [@franklin](#):
>
> Can you elaborate on the semantics here? What modules does a snippet import implicitly? How do you deal with name collisions if multiple targets of your package define APIs of the same name? If my target declares a function that refers to an API from external dependencies (e.g., in parameter position), is my snippet able to import that external dependency so that I can call my function?

A module can import any of the libraries created in its host package. This was a compromise to allow for some flexibility without having to configure each and every snippet. It's possible that we might want to broaden that to libraries pulled in with dependencies–I think someone brought that up above.

I'm not sure I understand what you mean regarding name collisions. These are basically just executable targets. You still need to import libraries to get their APIs, so if each library has their own `foo`, you need to use `A.foo` or `B.foo` to differentiate, same as any Swift code.

> [@franklin](#):
>
> What is the purpose of groups from a user (consumer) perspective? Are they just a way for package authors to organize their snippets? Do these need to be explicitly treated in SwiftPM or can they just be "folders"?

This started out as a formal thing that would create semantic groupings, but I made a change to just allow subdirectories without affecting the outgoing Symbol Graph data. Basically, the extra level of subdirectories is purely for organization, and the limit of depth one allows folks to put snippet-related resources in deeper directories without having to resort to fancy naming.

> [@franklin](#):
>
> ```swift
> //! Line comments prefixed with ! will
> //! serve as the snippet's short description.
> 
> ```
> 
> 99.9% sure about this, but just checking: this is Markdown content, right? 🙂

You know it! 😄

---

_[View the full topic](https://forums.swift.org/t/pitch-swift-snippets/56348)._
