Swift-DocC plugin for SwiftPM

ethankusters · January 21, 2022, 1:48am

I think a CLI flag makes a lot of sense here. We should start with a bug on bugs.swift.org and a specific forums thread to work through the naming but I think that would be a great enhancement.

Long-term, I'd like to expose some kind of static configuration for this so you wouldn't need to pass it as a flag every time if, for example, your DocC catalog is specifically designed around internal framework documentation. But the question of where that configuration should live is a can-of-worms I'm still thinking about

The plugin actually already does this to some extent, it will automatically include internal symbols for executable targets since its unusual for symbols in those targets to be marked public.

You can see that code here:

github.com

apple/swift-docc-plugin/blob/main/Plugins/SharedPackagePluginExtensions/Target+defaultSymbolGraphOptions.swift#L16


      
          // See https://swift.org/LICENSE.txt for license information
          // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
          
          import PackagePlugin
          
          extension SwiftSourceModuleTarget {
              /// Returns the default options that should be used for generating a symbol graph for the
              /// current target in the given package.
              func defaultSymbolGraphOptions(in package: Package) -> PackageManager.SymbolGraphOptions {
                  let targetMinimumAccessLevel: PackageManager.SymbolGraphOptions.AccessLevel
                  
                  if kind == .executable {
                      // The target represents an executable so we'll use an 'internal' minimum
                      // access level.
                      targetMinimumAccessLevel = .internal
                  } else {
                      // Since the target isn't an executable, we assume it's a library and use
                      // the 'public' minimum access level.
                      targetMinimumAccessLevel = .public
                  }