(How) Can I use DocC for internal documentation?

As presented in the talks and documentation I’ve seen so far, DocC works for public and open Swift symbols. But how about stuff for internal use? We are developing a fairly complex mixed source SDK with several components, that would benefit greatly from direct integration of auxiliary content for diagrams and so on. But since many of these parts are for internal use only, they have module or below level visibility. Is there a way to build an internal documentation target that includes this information with DocC, and — if so — how?

Answered by Documentation Engineer in 677843022

You are correct, DocC generates documentation for the public symbols in your framework or package. As you can imagine, that was the first priority, but your case certainly is interesting.

Could you please file a Feedback Assistant request with details about your project’s setup and what you’d like to be able to do? These types of enhancement requests, especially with how you'd like to see it work, are super helpful.

Thanks!

You are correct, DocC generates documentation for the public symbols in your framework or package. As you can imagine, that was the first priority, but your case certainly is interesting.

Could you please file a Feedback Assistant request with details about your project’s setup and what you’d like to be able to do? These types of enhancement requests, especially with how you'd like to see it work, are super helpful.

Thanks!

-Deleted this post because it was not answer it's just a comment to this topic-

In personally, I thought that too! DocC is an amazing feature to create great documentation.

It'd be so much better if we use that for internal symbols. Because in a big application, there would be a bunch of symbols and they might be internal since those needed by only application target.

Any update on that topic ? I've basically got the same requirement. Need to document an internal framework, aka : all its structs and classes, and not just the public ones.

By a strange coincidence I just saw a thread about this on Swift Forums (-:

Share and Enjoy

Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

This has been a major deficiency in many source document tools I've used. It'd be great if DocC can fill the gap!

Accepted Answer

Since Tim answered this question there has been some changes and I wanted to chime in with an updated answer.

You can document any symbols from private to public, the easiest way to set the minimum access levels to document is via the swift package command from the command line.

First you need to generate your module's symbol graph:

swift package dump-symbol-graph --minimum-access-level private

Then you copy the symbol graph to your doc bundle and run docc like usual from the command line:

docc convert MyDocs.docc

Hey @icanzilb, first of all thank for that answer, but if it is possible, I would like to ask you something. After being trying to make sense to what you said (I am a newbie) I ended up realising that your solution can only be applied to when building a package, right? it doesn't work in case of building an App and wanting to have an Apple style documentation where the rest of the developers could have access to not only the public symbols but also to the private ones, does it? However, if it works, could you please explain how to do it? Thanks a million :)

That flag, -symbol-graph-minimum-access-level private, works well in non-packages too. Added to XCode 14 Project settings  

  • Build Settings
    • Swift Compiler - Custom Flags

the Documentation window now shows all private members of a Framework target.

However …

My real goal is to have auto-completion and symbol links function within code comments. And they still do not. It’s as if the editor is using an internal version of .doccarchive that still has only public members of my Frameworks.

If I type `` or <doc: in a /// comment I only get suggestions for public members. And if I manually enter a private symbol, I only get the “?” for its documentation. It’s a dead link.

Any ideas on how I can have the editor see the same thing that Developer Documentation does?

It looks like the flag -symbol-graph-minimum-access-level private doesn't work with XCode 15.

Two years and you still can't document your own stuff.

(How) Can I use DocC for internal documentation?
 
 
Q