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(_:)？

來源

2017-08-12 ma11hew28

如果您詢問有關文檔，我建議您查看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:)是它的實現方式（我們希望知道如何在該方法內引用此參數）。

來源

2017-08-12 17:32:23 Rob

好了，這不是我一直在尋找的答案，但感謝你的課呢。 :-)我想知道用於文檔目的的符號。我更新了我的問題，使其更加清晰。 – 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(_:)也是斯威夫特有效的表達式。）

來源

2017-08-12 23:12:36 OOPer

Swift文檔：實例/類型屬性/方法表示法

回答

相關問題