When using Apple DocC: How to not generate documentation? How to link to UIKit? How to generate docs for extensions?

Question

I am using DocC for the first time, and after reading your docs, there are 4 things I don't know how to do it, can you help me?

How can I mark public methods to tell DocC that I don't want to generate documentation for a specific method? For example, I have a CaruselView, which is a subclass of UIView. This subclass is overwriting the method layoutSubviews. And DocC is generating empty documentation. Not very nice. When using Jazz (another documenting system), I was able to use:

/// :nodoc:

But, what is the equivalent in DocC?

All the public methods I added to UIView, UIColor, UILabel... using extensions and files like "UIView+Extensions.swift, after I press Generate Documentation in Xcode, they don't appear in the documentation generated. Is this a DocC limitation or a bug? I mean, I see sections for classes, enums, structs... but nothing about extensions on UIKit classes/structs.

Apart from that, if one of my structs or classes references one of these methods (in the extension files), I don't know the syntax to create the link. For example, this does not work:

/**
 An enum for use when using `UIView/applyElevation(_:)`
 */

How should I do it? I guess I cannot link something that does not exist, due to my previous question.

Last question, using double quotes we can reference symbols inside our package/framework. That's working fine. But how can we link symbols from UIKit or other Apple frameworks? For example:

/// A `UIView` consisting of a combination of ``CarouselView``, ``FlagLabel``
/// and ``IconButton`` intended for displaying product information.

If I use

``UIView``

it does not work. What format should I use?

Thanks a lot for suggestions.

Dougall

Looks like 6 months , generating docs for extensions was not possible. Perhaps it is the same case nowadays: #68997295 – Dougall

Linking symbols from UIKit or other frameworks isn't supported yet. Here's a discussion about this feature request. github.com/apple/swift-docc/issues/208 – Lamentable

Answer 1

This capability to hide elements from DocC documentation is now available in Swift 5.8.

To change whether a symbol is shown in documentation, use the @_documentation(visibility:) attribute

The visibility: form expects an access control keyword (public, internal, private, etc). If it cannot parse one from the attribute (e.g. it was misspelled) then the compiler will emit an error.

The visibility in the attribute corresponds is checked against the "minimum access level" given to the Swift compiler when generating symbol graphs. (For example, when Xcode generates app-level documentation, it requests a minimum access level of internal so that the resulting documentation is useful for contributors to the app to see items that are available across the codebase.)

Source swift forums and Underscored Attributes Reference.

Wilmawilmar