Internal documentation

benjamin.g · December 13, 2021, 4:55pm

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 ?

Jon_Shier · December 13, 2021, 5:05pm

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.

Joseph_Heck · December 13, 2021, 6:09pm

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:

github.com

apple/swift/blob/main/test/SymbolGraph/EmitWhileBuilding.swift#L33-L36


      
          // RUN: %empty-directory(%t)
          // RUN: %target-build-swift %s -module-name EmitWhileBuilding -emit-module -emit-module-path %t/EmitWhileBuilding.swiftmodule -emit-symbol-graph -emit-symbol-graph-dir %t/ -symbol-graph-minimum-access-level private
          // RUN: %FileCheck %s --input-file %t/EmitWhileBuilding.symbols.json
          // RUN: %FileCheck %s --input-file %t/EmitWhileBuilding.symbols.json --check-prefix PRIV

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

benjamin.g · December 13, 2021, 6:13pm

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 ?

Joseph_Heck · December 13, 2021, 6:22pm

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.

Jon_Shier · December 13, 2021, 11:53pm

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.

jberry · December 19, 2021, 2:58pm

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:

High level introductory and cross cutting information, including information not directly related to specific build targets.
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?

Docs on non-framework target such as applications.
Docs on public as well as non-public classes/structs.
Docs not associated with an executable/framework target at all.
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.

robnik · August 2, 2022, 7:35pm

Is this available yet in Xcode build settings? I see you said "you're constrained to using a nightly build ...". I'm not sure what that refers to. I only build my projects with Xcode.

Joseph_Heck · August 2, 2022, 8:04pm

The control for level isn’t exposed through Xcode, so if you use it’s “Build Documentation” option you see under the Product menu, it will use the defaults: public symbols for libraries, and internal symbols for applications or executables.

With Xcode 13, or Xcode 14 (beta) installed, you can use xcrun on the command line to invoke Docc, and this release includes the command line versions that would allow those symbol level controls. you’d have to use it outside of Xcode, but it uses the version of Docc that ships as a part of Xcode. That's where you'd need to add -Xswiftc -symbol-graph-minimum-access-level -Xswiftc private as parameters to invoking DocC on the command line.

acecilia · August 14, 2022, 11:45pm

Hi

About documenting internal APIs and implementation with Swift-DocC, I believe it is not only about which access level to include when generating the documentation. Let me explain.

Current state of the art: DocC is mainly focused in documenting public swift code, so libraries authors can add documentation for consumers:

This resulted in current implementation, where the markdown syntax has been enhanced with the goal of being able to reference to symbols or other documentation articles in the catalog
Furthermore, using relative paths for those references ([see the readme](subdirectory/README.md) VS <doc:README>) is not a good idea because this kind of documentation is usually exported and hosted somewhere separated from the code (usually a website): in such scenario there is no access to the code or the documentation source of truth
As a result, jumping from the documentation (in the xcode documentation navigator) to the actual source code seems to be not supported at the moment, and also not much needed: consumers are not interested on internal implementation details but rather just the public API
The validation of the references used in documentation articles is limited: DocC checks that the references exists (that the linked symbol or article exists). This simple check is usually enough to validate that documentation is up to date with public API

When documenting internal API or code, I believe the goals change. Hosting the documentation away from the code is not desired. Instead, likely the documentation would always stay as part of the repository, next to the code, and will serve as documentation to share between the authors of the package/packages (not the consumers):

Jumping from an article to code becomes more relevant, as the developer reading the documentation is likely interested in the internal implementation details and files being discussed in the documentation article (including the file locations in the repository)
In this case not only swift code will need to be documented, but likely non-swift code needs also to be referenced from the documentation. For example, the .swiftlint.yml file may be referenced in the documentation in case the documentation wants to include a mention to the swiftlint setup of the package
Due to above, referencing specific lines in local files (that are not swift symbols or other documentation articles) may be relevant. Currently a link like [this](path/to/local/file.txt) opens the url https://developer.apple.com/documentation/path/to/local/file when clicked, instead of opening the local file relative to the documentation article path
If part of a monorepo, the documentation may need to include references to other packages in the repository (while those packages are not dependencies), or to arbitrary files. And validation of these references is also not trivial
Maybe think one way to think about it is: how would DocC benefit the markdown articles created for swift evolution in swift-evolution/proposals at main · apple/swift-evolution · GitHub?

Jason-Abbott · November 18, 2022, 11:25pm

That flag, -symbol-graph-minimum-access-level private, worked well in 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 XCode 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 (within the same Framework target), 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 the Documentation window does?

franklin · November 21, 2022, 8:57am

Link auto-completion in Xcode does not support compilations that set -symbol-graph-minimum-access-level private. Since the way Xcode performs DocC link resolution is specific to the Xcode product rather than the Swift-DocC open source project, I'd recommend filing a feedback report here: https://feedbackassistant.apple.com. Thank you!