Swift documentation: instance/type property/method notation

Question

To document Ruby, I'd write, eg, Time::now or Time#day. How do I document Swift?

That is, when documenting Swift, what is the notation for a type and its 1) type property or method or 2) instance property or method?

For example, in Ruby documentation, the symbol :: (two colons) denotes a class property or method, and the symbol # (number sign, hash, hashtag, or pound sign) denotes an instance property or method. So, Time::now means that now is a class property or method of Time, and Time#day means that day is an instance property or method of Time.

Does Swift documentation have such a notation syntax?

I know Swift documentation's function notation—for example, that the Swift append(_ newElement: Element) method for Array is documented as append(_:)—because I see many examples of this notation in Apple's documentation. But, how do I write Array#append(_:) for Swift?

Answer 1

Unfortunately Swift does not have an official or widely-accepted notation to distinguish type properties/methods and instance properties/methods with type name prefixed form.

(So, usual Swift programmers (even expert) cannot understand what you are asking.)

Type name prefixed form is actually used in the Swift book, but not so often.

As far as I checked:

• In some parts, type property is referred to in a form like UInt32.max, but as you see this is just using actual notation valid as Swift expression.

• In some other parts, type method is referred to as a form like LevelTracker.unlock(_:), but this also is a valid expression in Swift and I'm not sure Apple is using this as a documentation notation for type method. I cannot find an example in the Swift book with a short glance, but initializers are often referred to in a form like String.init(data:encoding:) and this is also a valid expression in Swift.

• For other cases, instance methods or properties are referred to as instanceVar.methodName(_:) or instanceVar.propertyName, of course instanceVar appears in a nearby code snippet and is not a type name, this actually is not what you are looking for.

And as you already know, in Apple's official references, methods or properties are shown with heading Instance method, Type method , Instance Property or Type Property. Or prefixed with class/static var/let, class/static func, var/let or func.

I cannot find an example with a very short survey, but some articles (including Apple's) may be referring to an instance method also in a form TypeName.methodName(_:) (or instance property as well.) Seems Swift community thinks distinguishing type members and instance members is not important.

I could not take much time, but seems it is obvious that

Swift does not have an official or widely-accepted notation to distinguish type properties/methods and instance properties/methods with type name prefixed form.

Maybe you need to write something like instance method Array.append(_:) to represent Array#append(_:).

(To note, Array.append(_:) is also a valid expression in Swift.)

Answer 2

If you're asking about documentation, I'd suggest you check out Jazzy, a tool for building documentation from your inline code comments. It's nice way to build stand-alone documentation from your code comments and it's consistent with Apple's conventions.

The basic convention that uses is as follows. Let's imagine that you have some class defined like follows:

/// 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
    }
}

Jazzy will generates documentation that looks like:

Note, it's just showing you the argument labels. If you tap on one, it shows you whether it's a type method and what the parameter names are:

---

In the original question it wasn't clear you were talking about documentation, so I discussed the conventions one encounters in code. That answer is below.

---

In Swift, it's . for both instance and property types.

It's simply a matter of what preceeds the .. If it is a type, it's a type property/method. Consider:

let b = Foo.bar

This is referencing type property bar for Foo type. But if what preceeds the . is an instance of a type, then you're dealing with an instance property/method. Consider:

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

In this case, qux is referencing an instance property of Baz, because b an instance of the Baz type.

---

At the risk of clouding the issue, a caveat to the above pattern is the use of "selectors" (an older Objective-C pattern) in Swift. In this case the choice of target indicates what the selector references. If you supply an instance for target, the selector is referencing an instance method. If you supply a type for the target, then the selector is referencing a type method. Thus, in this example, the selector is referencing an instance method:

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

Whereas the following will call a type method:

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

Note, in both of these two examples, if we're interacting within the same class, we generally omit the class name altogether. You only have to explicitly reference the type if it's in another class. But I include this target/selector pattern merely because it does show another, slightly different, use of the Class.method syntax.

But this exception is unique. The general pattern is xxx.yyy where if xxx is an instance of some type, then yyy is an instance property/method, whereas if xxx is the name of some type, then yyy is a type property/method.

---

The references of append(_ newElement:) as append(_:) is completely different thing. This is just a case where the first parameter, newElement has no external label, so it's called with no label, e.g. array.append(object). So append(_:) is just a notation that shows you how it's called (where we don't care what the internal parameter name is), but append(_ newElement:) is how it's implemented (where we do want to know how to refer to this parameter within the method).