DocC: Is it possible to truly compile the tutorial's code and get compiler errors/warnings

The idea is to make it easer to update documentation when API changes or when code is not correct.

Is it possible to make the code file declared like this:

@Code(name: "AppDelegate.swift", file: AppDelegate.swift)

And the content of the AppDelegate.swift file is:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        
        compiler error should be raised here
        
        return true
    }
}

After doing "Product > Build Documentation" the output gives the following documentation and there is not warning or errors during the build:

Thank you for your answers.

Accepted Reply

DocC doesn't build the tutorial code files for a few reasons:

  • The code files could be in any language, not just Swift.
  • The code files may represent multiple stages of the same file which wouldn't be buildable together. For example, if two code files show a class and add a method to that class there would be two colliding class definitions if both code files were built together.
  • The code files may require additional resources or dependencies—that aren't part of the tutorial project—to build.

If you are writing a tutorial about a project that is buildable on its own and wanted to verify that that project builds without errors; you would need to configure your project with one target that builds the code and one target that builds the tutorial and have them share code files. However, if your tutorials have multiple stages of the same file it's possible that you can't build all tutorial code files in a single target. In this case you may need to define multiple targets that represent different stages of the project.

  • Thank you very much for the detailed explanation that all makes sense, I just wanted to make sure that I’m not missing something cool in DocC that could be beneficial in this case. Using a separate target makes perfect sense.

Add a Comment

Replies

DocC doesn't build the tutorial code files for a few reasons:

  • The code files could be in any language, not just Swift.
  • The code files may represent multiple stages of the same file which wouldn't be buildable together. For example, if two code files show a class and add a method to that class there would be two colliding class definitions if both code files were built together.
  • The code files may require additional resources or dependencies—that aren't part of the tutorial project—to build.

If you are writing a tutorial about a project that is buildable on its own and wanted to verify that that project builds without errors; you would need to configure your project with one target that builds the code and one target that builds the tutorial and have them share code files. However, if your tutorials have multiple stages of the same file it's possible that you can't build all tutorial code files in a single target. In this case you may need to define multiple targets that represent different stages of the project.

  • Thank you very much for the detailed explanation that all makes sense, I just wanted to make sure that I’m not missing something cool in DocC that could be beneficial in this case. Using a separate target makes perfect sense.

Add a Comment