Adds support for NSUnsupported to indicate non-availiability, and use annotations

[alblue]

As suggested in https://lists.swift.org/pipermail/swift-corelibs-dev/Week-of-Mon-20170724/001254.html it would be desirable to have a differential macro (rather than NSUnimplemented()) to indicate whether the functionality is missing by design in this library, to distinguish it from things that are not yet implemented.

This change adds NSUnsupported() as a variant of NSUnimplemented() that has a different error message, and allows the code to be differentiated at the point of definition, as well as uses availability macros on specific methods and types known to not exist on other platforms.

Note that marking the APIs as unavailable instead of deprecated would mean that they would cause compile-time errors. We may want to do that in a future release.

[alblue]

@swift-ci please test

[alblue]

Looks like an unrelated failure:

  switch (name.getKind()) {

@swift-ci please clean test

[alblue]

@swift-ci please clean test

[alblue]

@swift-ci please test

[alblue]

@swift-ci please test

[pushkarnk]

@swift-ci please test

[ianpartridge]

As discussed on the mailing list, I support this general approach but think we should only add NSUnsupported() in this PR, not start using it as well. We can adopt it in future PRs, perhaps post Swift 4.

[alblue]

@ianpartridge There's no reason to not start using NSUnsupported() in place of NSUnimplemented() as it doesn't change the semantics (other than the failure error message). The @available macros are a separate implementation detail though; we could add those subsequently. But AFAIK the swift-4.0 branch has diverged from master anyway, so we're really targeting swift.next here anyway, not the 4.0 branch - at least, that's my understanding @parkera

[spevans]

@alblue I think the automerge into swift-4.0 branch for corelibs-foundation is still active (according to my github feed)

[ianpartridge]

Yes it is: a248ca2

[ianpartridge]

@alblue The semantics are changing though - if NSUnsupported() doesn't mean anything different to NSUnimplemented() then why add it? Deciding which APIs become NSUnsupported() will involve some discussion...

[alblue]

@ianpartridge The key difference between NSUnsupported() and NSUnimplemented() is that one may be implemented in the future, the other one won't be. And yes, deciding which APIs need to be annotated is part of the reason for kicking off this thread and change set. The thing is, NSPort and NSPortMessage are both mach-specific concepts, which doesn't make sense on non-mach platforms; and as per pull #857 the Bundle.unload isn't going to be implemented in this project either.

Finally, the goal of having a separate string is so that git grep NSUnimplemented() trends to zero, which won't be the case while it exists in functions that will never be supported ...

[ianpartridge]

I totally agree about making sure that NSUnimplemented() can trend to zero. And NSUnsupported() seems like a good idea.

But I wonder how we are going to decide which APIs become NSUnsupported() and which are just removed from the project. After all, Apple never included NSUserActivity (for example) here in the first place. Should we be adding those APIs and marking them NSUnsupported()? What are we saying the difference is between Foundation APIs that are missing and those that are marked NSUnsupported()?

[alblue]

Good question for @parkera – should we just remove the types instead of deprecating them?

[parkera]

If the type is there, but marked as unavailable (not deprecated), then it's a pretty clear signal that we do not intend for it to be used, as opposed to it looking like we somehow forgot it. Also, portability efforts would probably be easier.

On the other hand, it could add a bunch of noise.

[parkera]

There are a bunch of classes on Darwin that we didn't bother even stubbing out here, and it seems like a waste of time to go find all of them (plus categories on Foundation types that higher level frameworks provide on Darwin) and add them, just to mark them unavailable.

[alblue]

To simplify the contribution, I've rebased and just have the NSUnsupported() macro, which we can then add to types/functions subsequently. I can then push subsequent changes on individual types so we can debate those as needed.

@swift-ci please test

[ianpartridge]

@swift-ci please test

[ianpartridge]

Thanks @alblue