Hacker News Reader

Comment by lilyball | Hacker News Reader

It's unclear to me what you think Exhibit B is demonstrating. That's the documentation for CIColor.init(red:green:blue:alpha:), and it's documented. It creates a CIColor with the specified red/green/blue/alpha components. This is literally just a model object.

View on HN

A more fair comparison for B is probably https://docs.microsoft.com/en-us/dotnet/api/system.drawing.c.... Still illustrates the point, it's more informative.

There are no examples.

There's no need for examples because initializing objects/structs is such a basic feature of both languages that Apple supports, it should be taken as read that the reader knows how to do it.

    CIColor.init(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0)

    [[CIColor alloc] initWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]

Need may be too strong a word, but I've never seen documentation suffer because there were too many high quality examples.

Great documentation uses those examples to shine light on other features that go nicely with (in this case) CIColor or to highlight the right way to do common tasks.

In addition to this, many developers (such as myself) learn best by example. Seeing a new tool in use is almost always the fastest way for me to grok it.

Yeah but, again, we're talking about an initializer. An initializer doesn't need an example other than on the language's documentation page for initializers.

The comparison given was totally unfair, as pointed out by another user. Let's look at something more similar to LINQ's Distinct function.

Here's the Collection Types page from the Swift book: https://docs.swift.org/swift-book/LanguageGuide/CollectionTy...

Here's the examples from the API page for Swift's Collection type: https://developer.apple.com/documentation/swift/collection

Or for Sequence, also full of examples: https://developer.apple.com/documentation/swift/sequence

Here's a counter-example that someone else pointed out: https://docs.microsoft.com/en-us/dotnet/api/system.drawing.c...

It's very comparable and highlights the differences and lack of detail in Apple documentation well.

Reply on news.ycombinator.com