For cases where the Clang importer provides a defaulted argument,
e.g., "[]" for option sets and "nil" for optionals, remove the
corresponding arguments at any call sites that simply specify "[]" or
"nil". Such arguments are basically noise, and tend to harm
readability when there are low-content argument labels like "with:" or
"for".
Some examples from Lister:
self.updateUserActivity(AppConfiguration.UserActivity.watch,
userInfo: userInfo, webpageURL: nil)
becomes
self.updateUserActivity(AppConfiguration.UserActivity.watch,
userInfo: userInfo)
and
contentView.hitTest(tapLocation, with: nil)
becomes
contentView.hitTest(tapLocation)
and
document.closeWithCompletionHandler(nil)
becomes simply
document.close()
and a whole pile of optional "completion handler" arguments go away.
Swift SVN r31978
For methods with at least a single parameter, split the base name at
the last preposition, so long as there are no other verbs or gerunds
in between. This separates out the action of the method from the
description of the first parameter, the latter of which can still have
needless words removed. This is particularly fun with
appendBezierPath*:
func appendBezierPath(with _: NSRect)
func appendBezierPath(withPoints _: NSPointArray, count: Int)
func appendBezierPathWithOval(`in` _: NSRect)
func appendBezierPathWithArc(withCenter _: NSPoint, radius: CGFloat,
startAngle: CGFloat, endAngle: CGFloat, clockwise: Bool)
func appendBezierPathWithArc(withCenter _: NSPoint, radius: CGFloat,
startAngle: CGFloat, endAngle: CGFloat)
func appendBezierPathWithArc(from _: NSPoint, to: NSPoint, radius:
CGFloat)
func appendBezierPath(with _: NSGlyph, `in`: NSFont)
func appendBezierPath(withGlyphs _: UnsafeMutablePointer<NSGlyph>,
count: Int, `in`: NSFont)
func appendBezierPath(withPackedGlyphs _: UnsafePointer<Int8>)
@available(OSX 10.5, *)
func appendBezierPath(withRoundedRect _: NSRect, xRadius: CGFloat,
yRadius: CGFloat)
Note: "point" and "name" are terrible verbs.
Swift SVN r31976
"With" is an indication that the first argument is not the direct
object of the base name. Therefore, label the first argument with
everything that follows the "With". Examples:
- func addButtonWithTitle(_: String) -> NSButton
+ func addButton(title: String) -> NSButton
- func updateWithPanRecognizer(_: NSPanGestureRecognizer)
+ func update(panRecognizer: NSPanGestureRecognizer)
- func appendBezierPathWithRoundedRect(_: NSRect, xRadius: CGFloat,
yRadius: CGFloat)
+ func appendBezierPath(roundedRect: NSRect, xRadius: CGFloat,
yRadius: CGFloat)
Swift SVN r31872
When omitting words from the end of the base name because it is
redundant with the type of the first parameter leaves a hanging "With"
in the base name, drop that "with" and instead use the tail of the
base name as the label for the first parameter. The poster child for
this is -copyWithZone, which now turns into "copy(zone:)":
- func copyWith(_: NSZone) -> AnyObject
+ func copy(zone: NSZone) -> AnyObject
The intuition behind this change is that the "With" is stating that
the method isn't directly acting on its argument; rather, the argument
is something additional, and argument labels are a fine way to model this.
Swift SVN r31836
When dropping the redundant type information from a parameter name
would leave us with "with", instead drop the "with" and lowercase the
rest of the parameter name. It's still redundant information, but it's
less bad than simply "with".
Swift SVN r31835
When matching a word from a name to a word from a type, handle the
ambiguity between type prefixes (NS, UI) and acronyms (URL, HTTP) by
matching the name word to the end of the type word so long as we don't
have lowercase letters or underscores preceding the match. This
allows a name word "URL" or "HTTP" to match a type word like "NSURL"
or "NSHTTP" without having to hardcode knowledge of prefixes.
This mostly affects the omit-needless-words mode, but can also help us
identify more factory methods that can become initializers.
Swift SVN r31703
We intentionally avoid collapsing a method name down to just a
preposition. When we end up in such cases, prefer to strip leading
redundant type information (which corresponds to both context and
return types) rather than trailing type information. This can help
keep close method families together, e.g., in NSFontDescriptor:
- func fontDescriptorWith(_: UIFontDescriptorSymbolicTraits) -> UIFontDescriptor
- func fontDescriptorWithSize(_: CGFloat) -> UIFontDescriptor
- func fontDescriptorWithMatrix(_: CGAffineTransform) -> UIFontDescriptor
- func fontDescriptorWithFace(_: String) -> UIFontDescriptor
- func fontDescriptorWithFamily(_: String) -> UIFontDescriptor
+ func withSymbolicTraits(_: UIFontDescriptorSymbolicTraits) -> UIFontDescriptor
+ func withSize(_: CGFloat) -> UIFontDescriptor
+ func withMatrix(_: CGAffineTransform) -> UIFontDescriptor
+ func withFace(_: String) -> UIFontDescriptor
+ func withFamily(_: String) -> UIFontDescriptor
Note especially the first case, where we don't want to just go down to
"with" for the name, even though "SymbolicTraits" is redundant with
the parameter type.
Swift SVN r31702
When the start of a name describes both the type of the context and
the type of the result, and is followed by a preposition, the start of
the name is redundant with the 'self' value, so strip it off. For
example:
url.URLWithHTTPS
becomes
url.withHTTPS
Swift SVN r31701
When the prefix of a method/property name is restating the result
type, followed by "By" and then a gerund, drop everything up to the
gerund. For example:
func stringByAppendingString(string: String) -> String
becomes
func appending(string: String) -> String
Swift SVN r31683
When the type name we're looking at is a collection of some element
type, also try to match the plural form of the element type name. For
example:
- func deselectItemsAtIndexPaths(_: Set<NSIndexPath>)
+ func deselectItemsAt(_: Set<NSIndexPath>)
Swift SVN r31666
Identify gerunds by stripping off the "ing" and looking for a
verb. This lets us transform, e.g., "stringByAppendingString" to
"stringByAppending", since "append" is a verb.
Swift SVN r31660
The presence of a verb or preposition prior to the redundant part
provides a firm linguistic split that lets the actual argument fill in
for the reader. For other parts of speech (adjectives, especially)
it's awkward to transition from "reading part of the name" to "reading
the argument". This eliminates a significant number of bad omissions,
e.g., "setTextColor()" -> "setText()", and generally makes the
transformation more conservative.
Swift SVN r31656
"With" tends to have value in separating the verb of the base of a
method name from the description of the first argument. The poster
child here is "copyWithZone", where "copy(_:)" makes it sound like
we're copying the argument. We're considering a more nuanced rule that
can drop "With" in cases where it's not separating a verb from a
description of the argument; that will follow if we do come across
such a result.
Swift SVN r31627
While there are cases where it makes sense to drop the first argument
label in initializers---when they're primarily conversions---it's an
heuristic that produces poor results (e.g., init(_:) rather than
init(coder:)) more often than not. Thus, remove this heuristic.
Swift SVN r31626
We want to see the results of the omit-needless-words heuristics under
the assumption that we won't need to quote these argument labels in
the future, and it avoids some head-scratching to not have this
heuristic in place.
Swift SVN r31625
Specifically, "Ref", "Ptr", and dimensionality suffixes (1D, 2D, 3D)
in the type name should not prevent us from finding redundancy in type
information.
Swift SVN r31428
Sink the actual logic for omitting needless words way down into
Basic, so we can re-use it elsewhere. Tie the Clang importer into that
logic, mapping Clang types down to strings appropriately. NFC
Swift SVN r31233
llvm::Optional lives in "llvm/ADT/Optional.h". Like Clang, we can get
Optional in the 'swift' namespace by including "swift/Basic/LLVM.h".
We're now fully switched over to llvm::Optional!
Swift SVN r22477
Previously, this declaration:
typedef NS_OPTIONS(NSUInteger, NSABitmapFormat5) {
NSAA16d,
NSAB32d,
};
...would import with members .A16d and .B32d, which is not necessarily
correct. (Is it "NS_AA_16d", or "NSA_A_16d"?) Be more conservative here.
Swift SVN r17125
This makes a number of changes to the selector-splitting
heuristics. Specifically:
- Eliminate last-word splitting, and with it the notion of
multi-words. We only split at prepositions now.
- Introduce the notion of "linking verbs" such as "will" or
"should"; when these show up, we refuse to split a selector, which
helps with delegates.
- Eliminate the special case for "get" and "set". It wasn't
helping.
Swift SVN r16265
