При использовании Apple DocC: как не создавать документацию? Как сделать ссылку на UIKit? Как создавать документы для расширений?

Question

Я впервые использую DocC, и после прочтения ваших документов я не знаю, как это сделать, есть четыре вещи. Вы можете мне помочь?

Как я могу отметить общедоступные методы, чтобы сообщить DocC, что я не хочу создавать документацию для определенного метода? Например, у меня есть CaruselView, который является подклассом. Этот подкласс перезаписывает метод layoutSubviews. И DocC генерирует пустую документацию. Не очень хорошо. При использовании Jazz (другой системы документирования) я мог использовать:

      /// :nodoc:

Но что эквивалентно в DocC?

Все общедоступные методы, которые я добавил UIView, UIColor, UILabel... используя расширения и файлы, такие как "UIView+Extensions.swift, после того, как я нажму Generate Documentationв Xcode они не появляются в созданной документации. Это ограничение DocC или ошибка? Я имею в виду, что я вижу разделы для классов, перечислений, структур ... но ничего о расширениях классов / структур UIKit.

Кроме того, если одна из моих структур или классов ссылается на один из этих методов (в файлах расширений), я не знаю синтаксиса для создания ссылки. Например, это не работает:

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

как мне это сделать? Думаю, я не могу связать то, чего не существует, из-за моего предыдущего вопроса.

Последний вопрос: используя двойные кавычки, мы можем ссылаться на символы внутри нашего пакета / фреймворка. Работает нормально. Но как связать символы из UIKitили другие фреймворки Apple? Например:

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

Если я использую

      ``UIView``

это не работает. Какой формат использовать?

Большое спасибо за предложения.

Answer 1

Эта возможность скрывать элементы из документации DocC теперь доступна в Swift 5.8.

Чтобы изменить отображение символа в документации, используйте команду@_documentation(visibility:)атрибут

The visibility:форма ожидает ключевое слово контроля доступа (public, internal, private, etc). Если он не может проанализировать один из атрибутов (например, он был написан с ошибкой), то компилятор выдаст ошибку.

Видимость в соответствующем атрибуте проверяется по «минимальному уровню доступа», заданному компилятору Swift при создании графов символов. (Например, когда Xcode генерирует документацию уровня приложения, он запрашивает минимальный внутренний уровень доступа, чтобы результирующая документация была полезна для участников приложения и могла видеть элементы, доступные в базе кода.)

Источник: форумы Swift и справочник по подчеркнутым атрибутам.