Hi folks,

I'm working on a project called swift-doc-testing, a bundle of a Swift CLI and a VSCode extension for building and testing code snippets in documentation comments (for swift packages). I want to take this post as an opportunity to share the purpose and uses of this project, and would love to hear your feedback: how likely you'd use this? what features you'd like to have for such too?

https://preview.redd.it/i7lfzmg027ug1.png?width=3680&format=png&auto=webp&s=d62dd75acf2cd98ecff37edea8540ff00af98a7a

Problems to solve:

Code snippets in doc comments alongside implementation code is useful and convenient. They provide context and usage, itself serving as an intuitive, irreplaceable documentation.

However, they often suffer from the following issues:

• code snippets are not compiled/checked by the compiler, thus prone to errors and difficulty in maintenance
• code snippets can be hard to format automatically, which also makes maintenance harder
• code snippets that are complex may not be readable for doc writers, given the absence of syntax highlight

This Project Offers

• a CLI that can
  • extract code snippets in doc comments
  • apply formatting automatically to doc comments
  • compile and run test snippets as tests given a doc test template
  • initialize a doc test template and provide convenient edit functionality
• a VSCode plugin that uses the CLI and
  • gathers discovered code snippets in doc comments
  • compiles and runs the code snippets as tests (with swift-testing), integrates test results over swift-testing's event stream to native VSCode test system

This project targets documentation code testing in swift packages, not xcode projects.

How It Works

Discovery

In a Swift doc comment like the following

    /// Returns `true` if the list contains no elements.
    ///
    /// Example with empty and non-empty lists:
    ///
    /// ```swift
    /// let empty = LinkedList<Int>()
    /// #expect(empty.isEmpty)
    ///
    /// var nonEmpty = LinkedList<String>()
    /// nonEmpty.append("item")
    /// #expect(!nonEmpty.isEmpty)
    /// ```
    public var isEmpty: Bool {
        head == nil
    }

The CLI picks up the code in code fence that has a swift language tag, and has the option to interpret code fences without a language tag as swift code.

```swift
```

Additionally, it currently supports test options, inspired by rustdoc test:

• @no-check: skips checking the code fence
• @compile-fail: asserts such code snippet fails to compile

and several on my todo list:

• @compile-only: only compiles
• @assert-error: test throws error

The options can be used like the following, similar to the code block annotation capability introduced in swift 6.3

```swift, @no-check
```

Test harness Generation

The CLI helps generate a DocTest folder under the client Swift package (swift-doc-testing edit init), which is a Swift package of the following structure.

❯ tree DocTest
DocTest
├── Package.swift
└── Tests
    └── DocTestTemplate
        └── DocTestTemplate.swift

You can setup the testing environment like you normally would for Swift packages, for instance

// swift-tools-version: 6.3
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "DocTestTemplate",
    dependencies: [
        .package(name: "client-package", path: ".."),
        .package(url: "https://pending.com/swift-doc-testing-utils", from: "0.0.1"),
    ],
    targets: [
        .target(
            name: "TestUtils",
            path: "Tests/Utils",
        ),
        .testTarget(
            name: "DocTestTemplate",
            dependencies: [
                .product(name: "Product", package: "client-package"),
                .product(name: "SwiftDocTestingUtils", package: "swift-doc-testing-utils"),
                "TestUtils",
            ],
        ),
    ],
    swiftLanguageModes: [.v6]
)

The test template is a file named DocTestTemplate.swift under the DocTestTemplate target, that will be used to scaffold test targets using doc code with the help of swift syntax.

import SwiftDocTestUtils
import Testing

#importSourcePackage()

@Test
func `#docTestIdentity`() {
    #injectDocTests()
}

For instance, a scaffolded test is

// file: docTest_LinkedList_isEmpty_0.swift

import SwiftDocTestUtils
import Testing
import DocTestExample

@Test
func `docTest_LinkedList_isEmpty_0`() {
    let empty = LinkedList<Int>()
    #expect(empty.isEmpty)

    var nonEmpty = LinkedList<String>()
    nonEmpty.append("item")
    #expect(!nonEmpty.isEmpty)
}

Test Runner

The test runner runs tests using swift test with --experimental-event-stream-output to obtain test execution information. It runs different categories (compile only, compile fail, etc.) separately.

VSCode Integration

VSCode extension

The extension adds a collection of discovered tests, just like the official swift plugin. You can run the tests just like the official swift plugin.

Edit Doc Test Template

The CLI provides a command that composes a temporary directory, hosts the doc test template package, and opens it in VSCode. This is to reduce friction of editing doc test template.

Current Status

I'm close to having a MVP that supports what's described in the previous section, and hopefully can open-source it in the upcoming week. A big chunk of the VSCode extension was built with Claude's help, and I want to make sure things are tested and work before released.

I'm also sorting out how to provide the best friction-less and feature-rich user experience. If you can think of anything you'd like to use, please let me know. I greatly appreciate any feedback.

TODO List

• My initial vision is to provide syntax highlight and LSP for the code snippets in doc comments. Syntax highlight seems possible, but LSP may require more work, as currently doc tests are run in one-time temporary directories.
• Optimizations to doc test compilation, such as organizing caching more efficiently, since users are likely to reuse the same packages across groups of doc tests for a given package.
• Support different templates for different options, such as allowing compile-fail to have a dedicated test template.

Thanks for reading! Would love to hear your thoughts!!

For those actively writing TODOs in your Swift code, Bar Ticket detects them and automatically creates a GitHub issue.

• Type //TODO in any editor → hit save → GitHub issue created automatically.
• macOS notch confirms it.
• No forms.
• No context switching.

I built this because my organization runs our project management via GitHub. Anytime I notice a bug in the code while I was working on a feature, I hate the process of navigating to GitHub and filling a ticket.

For the new developers out there, build an app that fixes your own problems. Most likely, others are having that same exact problem.

Download Here

This week, our friends at Manning Publications have provided a valuable discount on their new book, Grokking Data Structures. Check it out!

Hi all!

I have recently gotten so obsessed with the world of AI, and decided to build my own AI chatbot app in swift.

I am learning as I go, and so far I have a fully working app, multiple models, and different features and integrations in the app.

I am just needing some help with getting the AI to generate rich text that is actually formatted well and properly, like most AI chatbot apps are.

I completely understand, that acheiving the formatting that Gemini or Claude isnt going to be as easy for someone who has never built an app before, but i thought id reach out for some support to the community.

I would really appreciate some help, someone who could somewhat be a mentor while I learn, fail and learn!

I apologise for not providing technical specifics for how it is set up, im still learning that myself lol, however I know i am using a WKWebView (hopefully that makes sense)

There are some other issues, which include lag, freezing for a few seconds, pausing, which all are a pattern.

They happen at the same time, after I click specific buttons or navigate to specific areas (e.g. going into my chatscreen after a build & run), on the app startup and more! These happen EVERY time, for a similar length of time, at the same spots, and i am struggling to figure this out without breaking things and making it worse!

Thank you for your time reading this, and I would genuinley appreciate the support! ☺️

Hey coders,

What is Krisp? For those who don't know, Krisp is a specialized "virtual microphone" app that uses AI to separate your voice from everything else. It "listens" to your audio and instantly deletes barking dogs, crying babies, and keyboard clicks before the sound reaches your Zoom or Teams call. It’s a lifesaver for professional audio, but it’s currently locked behind a $120/year subscription that prices out many students and freelancers.

We’ve all reached "subscription fatigue." Paying that much for a basic utility feels like a "tax on quiet."

The Vision:

I’m calling on the dev community to build (or surface) a 100% free, open-source, AI-powered noise cancellation app for macOS and iOS. We have the tech (DeepFilterNet3, RNNoise), but we lack a unified, user-friendly "Krisp Killer" that works system-wide.

The "Absolute Best" Requirements:

• Universal Compatibility: Must be a Universal Binary supporting both Intel-based Macs (AVX/CPU optimized) and Apple Silicon (M1/M2/M3/M4). We need to ensure students and others on a budget with older hardware aren't left behind.
• 100% Offline & Private: No "home-calling," zero telemetry, and zero logs. All AI processing stays on-device. By being 100% offline, we eliminate the risk of a server-side breach leaking private meeting audio.
• Pro Features for Free: Include Room Echo Removal (Dereverberation) and "Studio Quality" voice enhancement. Unlike proprietary apps, open-source allows for community-tuned "Natural Voice" profiles that avoid that "robotic" processed sound.
• High Performance: The goal is real-time performance with low latency (<20ms)—faster than the human ear can detect.

Why this is the perfect project right now:

1. Hardware is Ready: Modern Macs have dedicated Neural Engines ($ANE$), and Intel Macs have the raw power for optimized models like DeepFilterNet3. Leveraging the $ANE$ on Silicon means the laptop won't sound like a jet engine or drain the battery just to stay quiet.
2. Vibecoding & AI Tools: With current AI coding assistants, building the system-wide audio driver (AudioDriverKit) and the GUI is more accessible than ever for a solo dev or small team.
3. The Tech Gap: Windows has NVIDIA Broadcast. Mac/iOS users are trapped between "basic" built-in tools and expensive, privacy-invasive subscriptions.

Who benefits the most?

• Privacy-Conscious Users: Open-source means the code is auditable. Your meetings never touch a cloud.
• The "Coffee Shop" Freelancer: Professional audio in a chaotic environment without the monthly fee.
• Low-Income Students: High-quality remote education shouldn't be gated behind a subscription. A free tool levels the playing field for global equity.

Real-World Use Cases:

• The "Mechanical Keyboard" Coder: Pair-programming while your tactile switches sound like a machine gun to your partner.
• The "Emergency Child/Pet" Interruption: Joining a high-stakes interview while the dog is barking at the door.
• The "Airport Gate" Professional: Taking a Teams call from a noisy terminal using only an iPhone or iPad.

The Challenge:

Who is interested in starting a Repo? Let’s make professional-grade, private communication a right, not a subscription service.

These AI models still need human review and supervision. They can’t generate code without human oversight. For instance, during a PR review with my manager, I found it embarrassing when Claude generated nonsensical, repetitive, and redundant content. I had to step back and review the generated content before it was pushed to production.