Internal documentation

Hi, i've been looking for a way to use swift-docc for documenting the internals of a (fairly large) custom framework, the target audience being internal developpers that will later have to maintain or port the framework to other platforms, without much success.

Is there any way to do so or will I have to rely on marking every class & struct i wish to document as public ?

Ideally DocC would add the ability for users to set a base access level for the generated documentation. In the meantime, you might be able to use Jazzy to do what you need, rather than polluting your code with unnecessary ACLs.

3 Likes

That capability is available in the nightly builds now - or at least you can kind of shim into it. There's a CLI option to specify the access level (defaults to 'public') of the symbols in the symbol graph to include from the compiler. To use this, you need to add some options to the swift build command that's generating the symbol graph.

So in addition to something like:

    -Xswiftc -emit-symbol-graph \
    -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs

You would add:

   -Xswiftc -symbol-graph-minimum-access-level -Xswiftc private

^^ or something along those lines. It was referenced obliquely in this forum a while ago, but when I searched, I couldn't easily spot the reference again. ;-)

To get the detail about this option, I had to look through the source: swift/Options.td at main · apple/swift · GitHub

And the related test that works it:

I tried it out, and it definitely works, but you're constrained to using a nightly build to get at this option right now.

3 Likes

Thanks a lot, i'll try it out asap !

Any idea at which point i can hope this feature to be available directly in the xcode build ?

I wouldn't expect it to be available in an Xcode build until at least Swift 5.6 is what's shipped with an Xcode - so maybe in January (guessing from Xcode 12's january update release), but I think it's a safer bet to expect with Apple's normal spring time release (historically in the April timeframe).

The code was merged into the main branch ~2 months ago (Thank you @QuietMisdreavus !), but I don't know how that lines up to Apple's upcoming releases of swift within Xcode.

2 Likes

Xcode 12 was released in Sept. 2020. Usually Swift releases on a 6 month cycles, so Swift 5.6 would be March 2022, like 5.4 was in '21, and 5.2 was in '20.

1 Like

We’re interested in using docc to generate internal documentation (I.e., documentation to be consumed internally by our teams) that covers several module types, including application and framework targets. Ideally that list would even include generic non-code targets for high level reference and introductory information.

Perhaps it’s useful to think of the portfolio of the things a development team has to deal with:

  1. High level introductory and cross cutting information, including information not directly related to specific build targets.
  2. Documentation concerning individual targets, and very specifically both applications and frameworks, covering classes both public and private.

… and once-written, to be able to statically host such files on a service such as GitHub pages, automatically as part of a ci process.

I’ve been following along just enough to perceive, I think, that most of that is not possible with the current docc release, but that some of it may be possible in the next release. Can anybody summarize the current state of progress on what seem to be the following pain points?

  1. Docs on non-framework target such as applications.
  2. Docs on public as well as non-public classes/structs.
  3. Docs not associated with an executable/framework target at all.
  4. Generation of docs suitable for static hosting.

I’d love to know (a) whether any of that is possible today using official docc releases and (b) what is likely to be available in the next release. These are things which currently seem to gate our ability to use docc: having these abilities would make it a useful tool for us.

Thanks.

Terms of Service

Privacy Policy

Cookie Policy