Быстрая документация Комментарии

У меня есть несколько вопросов о комментариях документации Swift.

  • Есть ли какой-либо способ сделать раздел Связанные объявления, как некоторые из документации Apple. Например, когда я вариант + щелкните метод tablewView (_: heightForRowAtIndexPath:), он свяжет меня с тремя другими связанными методами в сгенерированной документации.

  • Есть ли какой-либо предупреждающий тег в swift? Я знаю, что в objective-c это позволило вам сделать @warning и получить полужирное предупреждение в создаваемой документации. Однако: предупреждение: ничего не делает в быстрых комментариях документации, поэтому мне было любопытно, есть ли другой способ.

  • Есть ли способ сделать вашу документацию в HTML файл, который аналогичен формату Apple Documentation. Я знаю, что в других IDE для других языков, таких как Eclipse, вы можете просто генерировать html-документацию для вашего кода. Есть ли у XCode это?

Ответы

Ответ 1

Вы можете использовать разметку для написания комментариев к игровой площадке и коду.

  • Для богатой игровой документации используйте //: или /*: */
  • Для документации кода используйте /// или /** */

пример

/// This function returns a *hello* string for a given 'subject'.
///
/// - Warning: The returned string is not localized.
///
/// Usage:
///
///     println(hello("Markdown")) // Hello, Markdown!
///
/// - Parameter subject: The subject to be welcomed.
///
/// - Returns: A hello string to the 'subject'.
func hello(subject: String) -> String {
    return "Hello, \(subject)!"
}

Ответы на ваши вопросы

Объявление. 1. Нет. Хотя есть SeeAlso разметки SeeAlso, он еще недостаточно умен, чтобы ссылаться на связанные символы внутри вашей или сторонней библиотеки.

Объявление. 2. Да, есть тег разметки Warning. Смотрите мой пример выше.

Объявление. 3. Хотя Xcode может генерировать XML-представление комментариев документации, он не может создавать HTML файл. Я рекомендую использовать Jazzy для этого.

Ответ 2

Xcode 7.0 beta 4

Обозначение было изменено (:param: больше не работает...)

/// Creates the string representation of the poo with requested size.
///
/// - warning: Be carefull! Poos can hurt.
/// - parameter size: requested size of the poo
/// - returns: string representation of the poo
func makePoo(size: String) -> String
{
    return "Ouch. This is \(size) poo!"
}

И это выглядит так:

PopUp с документацией

Вы можете использовать либо ///, либо /** */

Ответ 3

(3) Чтобы создать вашу документацию в HTML (или даже создать docset), я настоятельно рекомендую jazzy, который был создан для этой цели.

Даже если это еще WIP, он работает очень хорошо и создает документацию с похожим представлением в документации Apple

Ответ 4

Для кода Swift Apple удалила HeaderDoc и переключилась на стиль уценки. Они выбрали CommonMark вариант Markdown с некоторыми расширениями для ключевых слов Swift.

Документация по символам

Есть четыре раздела, из которых всегда включено только описание:

  • Описание
  • Параметры
  • Выдает
  • Возвращает

После описания порядок остальных разделов не имеет значения. У вас может быть только один раздел "Броски" и "Возврат".

/**
 What does this function do?

 Some discussion

 - Parameters:
    - firstParam: Describe the first param
    - secondParam: Describe the second param
 - Returns: true or false
 - Throws: SomeError you might want to catch
 */
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

или эквивалентный

/// What does this function do?
///
/// Some discussion
///
/// - Parameters:
/// - firstParam: Describe the first param
/// - secondParam: Describe the second param
/// - Returns: true or false
/// - Throws: SomeError you might want to catch
func someFunction(firstParam: String, secondParam: String) throws -> Bool {
    return true;
}

Если комментарий к документации начинается с чего-либо, кроме абзаца, все его содержимое помещается в обсуждение.

Краткое руководство по ключевому слову

Если вы хотите, чтобы получить фантазию, есть длинный список ключевых слов, которые вы можете включить в любое место в описании.

- Attention: - Author: - Authors: - Bug: - Complexity: - Copyright:
- Date: - experiment: - important: - invariant: - Note: - Precondition:
- Postcondition: - Remark: - Requires: - seealso: - Since: - Todo: - Version:
- Warning: и т.д.

Чтобы автоматически сгенерировать документ:

  • Xcode 11: ⌘ command + нажмите на свою функцию → Добавить документацию
  • ⌘ command + ⌥ option + /
  • Editor -> Structure -> Add Documentation.

Эти команды добавляют /// в начале каждой новой строки. Также вы можете добавить вручную /** в качестве первой строки и */ в последней строке вашего документа.

Как создать HTML для Swift & Objective-C, пожалуйста, посмотрите на jazzy из Царства

Подробнее здесь, здесь

Ответ 5

Используйте следующие обозначения для комментариев документации.

/**
 This method sum two double numbers and returns.

 - parameter number1: First Double Number.
 - parameter number2: Second Double Number.
 - returns: The sum of two double numbers.

 # Notes: #
 1. Parameters must be **double** type
 2. Handle return type because it is optional.

 # Example #
'''
 if let sum = self.add(number1: 23, number2: 34) {
  print(sum)
 }
 '''
*/


func add(number1: Double, number2: Double) -> Double? {
    return number1 + number2
}

enter image description here