(How) Can I use DocC for internal documentation?

Question

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?

DocC

4.4k

Posted by

Apfelmaennchen

Reply

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.

—
muukii0803

Add a Comment

Answer 1

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!

Posted by

TimTr

Thanks for the reply! Please see FB9144883, I’ll be able to provide more details as needed. The most important aspects (apart from documenting a superset of public ∪ open symbols) would be use of pictures for diagrams of general architecture, lock-acquisition-order etc. in internal documentation — also for Objective-C(++) (see: FB9144975).

—
Apfelmaennchen

Add a Comment

Answer 2

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!

Posted by

TimTr

Thanks for the reply! Please see FB9144883, I’ll be able to provide more details as needed. The most important aspects (apart from documenting a superset of public ∪ open symbols) would be use of pictures for diagrams of general architecture, lock-acquisition-order etc. in internal documentation — also for Objective-C(++) (see: FB9144975).

—
Apfelmaennchen

Add a Comment

Answer 3

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

Posted by

muukii0803

Add a Comment

Answer 4

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.

Posted by

benjamin181

Add a Comment

Answer 5

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"

Posted by

eskimo

Add a Comment

Answer 6

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

Posted by

dannys42

Add a Comment

Answer 7

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

Posted by

icanzilb

Ah, might have been a bit trigger happy here: this only works for SPM targets, not traditional Xcode targets, correct? That said, together with what Quinn referenced above, this should do the trick. I’ll give it a try when I’m back from my vacation.

—
Apfelmaennchen

Add a Comment

Answer 8

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 :)

Posted by

felishuck

Add a Comment

Answer 9

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?

Posted by

Jason Abbott

Add a Comment

Answer 10

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

Posted by

iAchilles

Add a Comment

(How) Can I use DocC for internal documentation?

Apple Recommended

Replies