I am in the midst of developing a package which will be an open source project.
I find that there are two audiences I need to write documentation for:
Clients who need documentation about the public interface and how to use it.
Contributors who need documentation about code internals: architecture, internal and private types, etc.
I am new to using DocC, but reading documentation and watching WWDC sessions, it seems like the current focus of DocC is around client documentation.
Are there any facilities to support contributor documentation as well?
For example, a way to generate documentation that includes articles geared towards contributors as well as non-public symbols in a separate documentation bundle?
Thanks in advance for any suggestions and insights.
we likely cannot provide documentation about private declarations, but fundamentally there is nothing preventing us from generating internal documentation at the symbol graph level.
i experimented with this a while ago on Swiftinit but got massive pushback from users who did not want non-public symbols showing up in the generated pages. so i’m not sure if there’s an approach that can satisfy everyone, at least for docs hosted on the internet.
I don't know enough about DocC internals to know what is and isn't possible. I can definitely understand folks wanting only public symbols for client documentation.
I am guessing there isn't a common convention for doing this, for example including a document catalog "Internals.docc" or some well-known name to generate a second bundle from a package.
I'm not sure that @taylorswift is entirely accurate here.
When you're generating your own documentation, what's happening under the covers is a symbol graph is getting generated, and the level of what symbols are included defaults to 'public' for libraries, and 'internal' for executables. You can absolutely control that level of generation yourself, but it's not "easy" when you're using the higher level tools of the docc-plugin or such. There's a bit of prior discussion from a year or so ago that goes into detail, allowing you to even go down to "private" if you like.
These controls are exposed as additional swift compiler flags - tl;dr:
That said, external tooling that's hosting documentation - such a @taylorswift UniDoc tooling, or the automated generation at SwiftPackageIndex.com (which fundamentally uses Xcodebuild under the covers) is a bit tricker to arrange.
right that’s why i said at the symbol graph level.
i’d be surprised if this works reliably, because private types can shadow each other, and we rely a lot on name-based lookup during documentation generation.
i believe both of those trees hold public documentation, for some reason we have just published some of the articles under a different domain.
My observation was that having one set of documentation for library clients and another set of documentation for library contributors was something that DocC already does. I didn't look deeply into the protection levels.
It just strikes me that with so many Swift projects inviting contributions, having a way to easily generate documentation for both audiences could be very useful.
weirdly enough, what you call the “user” documentation actually is just the module documentation for the docc executable target. it seems the “internal” documentation is just the public documentation for the SwiftDocC library target.
i don’t know why they are hosted in two different places, as they originate from the same package, and i assume were generated with similar settings. perhaps the @swift-website-workgroup can provide some background.
I’ve generally been of the same opinion, but haven’t chased it deeply - primarily because of the constraint that DocC can’t easily (yet? - it’s being worked on) be referenced by parallel modules.
In my case, I leaned into heavy internal comments for contributors, which is not nearly the same as detailed narrative, but is sufficing at the moment.
I’m also using another project with a demo app that uses the library - and displaying its internal methods - as a means of providing walk-through like examples, options, and tradeoffs in choices when using the library. Again, more for external users than contributors - but I’d love to wrangle something similar for contributor docs.
I can’t speak for the DocC team, but I don’t think this was intended as contributor documentation, but since DocC’s inception has gradually grown more “internal”, as docc the executable is more and more (intentionally) hidden and common usage of it is done with wrapped tools (docc-plugin).