[swift-evolution] [Guidelines, First Argument Labels]: Prepositions inside the parens

[Douglas Gregor]

> On Feb 9, 2016, at 11:50 AM, Jacob Bandes-Storch via swift-evolution <swift-evolution at swift.org> wrote:
> 
> I think I like this direction in general. It feels more natural to have the preposition in the label than outside the parenthesis (and it's worth keeping the preposition because it improves clarity in most cases).
> 
> Here are some strange examples which need tweaking:
> 
>      + func accountType(withAccountTypeIdentifier typeIdentifier: String!) -> ACAccountType!
> 
> Probably should just be "withIdentifier”.

Interesting! I’ll have to think about this; it might just be a special case. I haven’t seen this issue come up before.

> 
>      + func comparePositionInDecodeOrderWithPosition(of cursor: AVSampleCursor) -> ComparisonResult
> 
> I would suggest comparePositionInDecodeOrder(withPositionOf cursor: AVSampleCursor). Tricky because there are two prepositions.

Yeah. Our current heuristics produce:

	func comparePositionInDecodeOrder(positionOf cursor: AVSampleCursor) -> ComparisonResult

> 
>       func componentsPassingTest(testHandler: (AVAudioUnitComponent, UnsafeMutablePointer<ObjCBool>) -> Bool) -> [AVAudioUnitComponent]
>  -    func componentsMatching(desc: AudioComponentDescription) -> [AVAudioUnitComponent]
>  +   func components(matching desc: AudioComponentDescription) -> [AVAudioUnitComponent]
> 
> Should "passingTest" become the first label?

Yes, thanks!

	https://github.com/apple/swift-3-api-guidelines-review/commit/ba288337414c998fa358312e22c9b2660dd334e4

>      -  class func exportPresetsCompatibleWith(asset: AVAsset) -> [String]
>      +  class func exportPresetsCompatible(withAsset asset: AVAsset) -> [String]
> 
> This is not an improvement. I'd suggest exportPresets(compatibleWith asset: AVAsset), but that doesn't really fit under the current rules. Maybe a special case for [noun][adjective][preposition]?

I did it in a different way, here:

	https://github.com/apple/swift-3-api-guidelines-review/commit/fd70e0e4fa026843ab6570d1b2d46a4cbfd13974

> 
>     -  func compatibleTrackFor(compositionTrack: AVCompositionTrack) -> AVAssetTrack?
>     +  func compatibleTrack(forCompositionTrack compositionTrack: AVCompositionTrack) -> AVAssetTrack?
> 
> Does this indicate that some other suffix-matching rules are no longer being applied? I'd have expected compatibleTrack(for compositionTrack: AVCompositionTrack). I also see other examples like renewCredentials(forAccount account: ACAccount, …).

There was a ban on leaving “vacuous” argument labels like “for” or “with”, but it doesn’t make sense now. Addressed in

	https://github.com/apple/swift-3-api-guidelines-review/commit/aaec8d0fe9cf82cd6f4088721cf8968a6ac69164 <https://github.com/apple/swift-3-api-guidelines-review/commit/aaec8d0fe9cf82cd6f4088721cf8968a6ac69164>

> 
>       func createSampleBufferFor(request: AVSampleBufferRequest) -> CMSampleBuffer
> 
> Why wasn't this changed?

Similar issue to the rule above. It’s fixed now to 

	func createSampleBuffer(for request: AVSampleBufferRequest) -> CMSampleBuffer

> 
>       -  class func typeOf(property property: String!) -> ABPropertyType
>       +  class func type(ofProperty property: String!) -> ABPropertyType
> 
> I don't really like either of these. Maybe we need special rules for "of” ?

Handled in the subsequent discussion ;)

> 
> If anyone else is worried about special cases, I just looked this up: there's a clang __attribute__((swift_name("x"))), or NS_SWIFT_NAME(x), which can be used to expose Obj-C methods to Swift with particular custom names.

Yes, generalizing the swift_name attribute to allow arbitrary renaming is one of specified steps to implementing SE-0005, so we can deal with special cases and bad translations.

Thanks!

	- Doug

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160212/bd7229c2/attachment.html>