Swift文档：实例/类型属性/方法表示法

问题描述：

要记录Ruby，我会写，例如，Time::now或Time#day。我如何记录Swift？Swift文档：实例/类型属性/方法表示法

也就是说，当记录Swift时，类型及其1）类型属性或方法或2）实例属性或方法的符号是什么？例如，在Ruby文档中，符号::（两个冒号）表示一个类属性或方法，而符号#（数字符号，哈希，哈希标签或井号）表示一个实例属性或方法。因此，Time::now表示now是Time的类属性或方法，而Time#day表示day是Time的实例属性或方法。

Swift文档是否有这样的符号语法？

我知道Swift文档的函数表示法，例如Swift append(_ newElement: Element) method for Array记录为append(_:)，因为我在Apple的文档中看到了很多这种表示法的例子。但是，如何为Swift编写Array#append(_:)？

答

如果您询问有关文档，我建议您查看Jazzy，这是一种从内联代码注释构建文档的工具。从代码注释中构建独立文档是非常好的方式，并且符合Apple的惯例。

使用的基本约定如下。让我们想象一下，你有一些类定义如下所示：

/// Some incredibly useful class 

public class MyClass { 

    /// Performs some foo-like operation 
    /// 
    /// - Parameter bar: The bar parameter. 

    public class func foo(_ bar: String) { 
     // do something 
    } 

    /// Some bazzy operation 
    /// 
    /// - Parameter qux: The bar parameter. 

    public func baz(_ quz: String) { 
     // do something 
    } 
}

爵士将产生的文件看起来像：

注意，它只是显示你的参数标签。如果你在一个水龙头，它表明你是否是一个类型的方法，什么参数名：

在原来的问题，目前还不清楚你在谈论的文件，所以我讨论了在代码中遇到的约定。答案如下。

在Swift中，实例和属性类型都是.。

这只不过是.之前的问题。如果它是一个类型，它是一个类型属性/方法。试想一下：

let b = Foo.bar

这是引用类型属性bar为Foo类型。但是如果.的前面是一个类型的实例，那么你正在处理一个实例属性/方法。试想一下：

let b = Baz() 
let q = baz.qux

在这种情况下，qux所引用的Baz实例属性，因为b的Baz类型的实例。

在混浊问题的风险，告诫到上面的图案是用在雨燕“选择”（旧的Objective-C的图案）。在这种情况下，target的选择指示selector引用的内容。如果您提供target的实例，则selector正在引用实例方法。如果您提供target的类型，则selector正在引用一种类型方法。因此，在这个例子中，selector所引用的实例方法：

Timer.scheduledTimer(timeInterval: 1, target: self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)

而下面将调用类型的方法：

Timer.scheduledTimer(timeInterval: 1, target: ViewController.self, selector: #selector(ViewController.foo), userInfo: nil, repeats: false)

注意，在这两个的这两个例子，如果我们在同一个班级内进行互动，我们通常会完全忽略班级名称。如果它在另一个类中，则只需显式引用该类型。但是我仅仅包含这个target/selector模式，因为它确实显示了另一种略有不同的语法使用。

但是这个例外是独一无二的。一般模式是xxx.yyy，如果xxx是某种类型的实例，则yyy是一个实例属性/方法，而如果xxx是某种类型的名称，则yyy是一个类型属性/方法。

的append(_ newElement:)为append(_:)的引用是完全不同的事情。这只是第一个参数newElement没有外部标签的情况，所以它被称为没有标签，例如， array.append(object)。因此append(_:)只是一个表示它如何被调用的表示法（我们不关心内部参数名称是什么），但append(_ newElement:)是它的实现方式（我们希望知道如何在该方法内引用此参数）。

好了，这不是我一直在寻找的答案，但感谢你的课呢。 :-)我想知道用于文档目的的符号。我更新了我的问题，使其更加清晰。 – ma11hew28

答

不幸的是，Swift没有官方或广泛接受的表示法来区分类型属性/方法和实例属性/方法与类型名称前缀的形式。

（所以，通常斯威夫特程序员（甚至是专家）无法理解你的要求。）

类型名称前缀形式在Swift book实际使用，但不是经常。

至于我检查：

在一些地区，类型物业的形式，您认为这仅仅是用实际符号作为斯威夫特表达有效简称像UInt32.max，但。
在其他一些部分，类型方法被称为LevelTracker.unlock(_:)等表单，但这也是Swift中的有效表达式，我不确定Apple是否将此用作类型方法的文档记号。我无法在Swift书中找到一个简短的示例，但初始化程序通常以String.init(data:encoding:)这样的形式引用，这也是Swift中的有效表达式。
对于其他情况，例如方法或属性被称为instanceVar.methodName(_:)或instanceVar.propertyName，当然instanceVar出现在附近的代码片段，而不是一个类型名称，这其实是不是你在找什么。

正如你已经知道，在苹果官方引用，方法或属性，只显示标题实例方法，类方法，实例属性或类型属性。或者前缀为class/static var/let,class/static func,var/let或func。

我找不到一个很短的调查的例子，但一些文章（包括苹果的）也可能指的是TypeName.methodName(_:)（或实例属性）形式的实例方法。似乎Swift社区认为区分类型成员和实例成员并不重要。

我不能花太多时间，但似乎很明显，

斯威夫特没有一个正式的或广泛接受的符号来区分类型的属性/方法和实例属性/类型名称方法前缀形式。

也许你需要写类似实例方法Array.append(_:)代表Array#append(_:)。

（要注意，Array.append(_:)也是斯威夫特有效的表达式。）

Swift文档：实例/类型属性/方法表示法

相关推荐