---

yaml
---
r: 348773
b: refs/heads/master
c: 414a4e2
h: refs/heads/master
i:
  348771: 75349aa

Author: jckarter

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: b93096c8c5172c1412b90f843d517114e9735db1
+refs/heads/master: 414a4e2a1cd8c506ea84018d4af8d8d0c88413ff
 refs/heads/master-next: 203b3026584ecad859eb328b2e12490099409cd5
 refs/tags/osx-passed: b6b74147ef8a386f532cf9357a1bde006e552c54
 refs/tags/swift-2.2-SNAPSHOT-2015-12-01-a: 6bb18e013c2284f2b45f5f84f2df2887dc0f7dea

trunk/docs/CToSwiftNameTranslation.md

@@ -212,6 +212,29 @@ Additionally, typedefs for `void *` or `const void *` that are themselves annota
 If a typedef's underlying type is itself a "CF pointer" typedef, the "alias" typedef will be imported as a regular typealias, with the suffix "Ref" still dropped from its name (if present) unless doing so would conflict with another declaration in the same module as the typedef.
 
 
+## Objective-C Properties
+
+By default, most property names are not transformed at all. However, if the getter of a property overrides a superclass or adopted protocol method that is also a property accessor, the Swift name of the overridden accessor's property will be used for consistency. If there's more than one such name, one is chosen arbitrarily.
+
+Properties with the type `BOOL` or `Boolean` use the name of the getter as the name of the Swift property by default, rather than the name of the property in Objective-C. This accounts for a difference in Swift and Objective-C naming conventions for boolean properties that use "is".
+
+```objc
+@property(getter=isContrivedExample) BOOL contrivedExample;
+@property BOOL hasAnotherForm;
+```
+
+```swift
+var isContrivedExample: Bool { get set }
+var hasAnotherForm: Bool { get set }
+```
+
+_This rule should probably have applied to C's native `bool` as well._
+
+A property declaration with the `SwiftImportPropertyAsAccessors` API note will not be imported at all, and its accessors will be imported as methods. Additionally, properties whose names start with "accessibility" in the NSAccessibility protocol are always imported as methods, as are properties whose names start with "accessibility" in an `@interface` declaration (class or category) that provides the adoption of NSAccessibility.
+
+_Objective-C code has historically not been consistent about whether the NSAccessibility declarations should be considered properties and therefore the Swift compiler chooses to import them as methods, as a sort of lowest common denominator._
+
+
 ## `swift_private`
 
 The `swift_private` Clang attribute prepends `__` onto the base name of any declaration being imported except initializers. For initializers with no arguments, a dummy `Void` argument with the name `__` is inserted; otherwise, the label for the first argument has `__` prepended. This transformation takes place after any other name manipulation, unless the declaration has a custom name. It will not occur if the declaration is an override; in that case the name needs to match the overridden declaration.
@@ -252,6 +275,8 @@ __attribute__((swift_name("SpacecraftCoordinates")))
 struct SPKSpacecraftCoordinates {
   double x, y, z, t; // space and time, of course
 };
+
+// Usually seen as NS_SWIFT_NAME.
 ```
 
 ```swift
@@ -287,12 +312,10 @@ The `swift_name` attribute can be used to give a C function a custom name. The v
 ```objc
 __attribute__((swift_name("doSomething(to:bar:)")))
 void doSomethingToFoo(Foo *foo, int bar);
-
-// Usually seen as NS_SWIFT_NAME.
 ```
 
 ```swift
-func doSomething(foo: UnsafeMutablePointer<Foo>, bar: Int32)
+func doSomething(to foo: UnsafeMutablePointer<Foo>, bar: Int32)
 ```
 
 An underscore can be used in place of an empty parameter label, as in Swift.
@@ -430,4 +453,86 @@ Although enumerators always have global scope in C, they are often imported as m
 
 _Currently, `swift_name` does not even allow importing an enum case as a member of the enum type itself, even if the enum is not recognized as an `@objc` enum, error code enum, or option set (i.e. the situation where a case is imported as a global constant)._
 
+
+### Fields of structs and unions; Objective-C properties
+
+The `swift_name` attribute can be applied to rename a struct or union field or an Objective-C property (whether on a class or a protocol). The value of the attribute must be a valid Swift identifier.
+
+```objc
+struct SPKSpaceflightBooking {
+  const SPKLocation * _Nullable destination;
+  bool roundTrip __attribute__((swift_name("isRoundTrip")));
+};
+```
+
+```swift
+struct SPKSpaceflightBooking {
+  var destination: UnsafePointer<SPKLocation>?
+  var isRoundTrip: Bool
+}
+```
+
+
+### Objective-C methods
+
+The `swift_name` attribute can be used to give an Objective-C method a custom name. The value of the attribute must be a full Swift function name, including parameter labels.
+
+```objc
+- (void)doSomethingToFoo:(Foo *)foo bar:(int)bar
+  __attribute__((swift_name("doSomethingImportant(to:bar:)")));
+```
+
+```swift
+func doSomethingImportant(to foo: UnsafeMutablePointer<Foo>, bar: Int32)
+```
+
+As with functions, an underscore can be used to represent an empty parameter label.
+
+Methods that follow the NSError out-parameter convention may provide one fewer parameter label than the number of parameters in the original method to indicate that a parameter should be dropped, but they do not have to. The `swift_error` attribute is still respected even when using a custom name for purposes of transforming an NSError out-parameter and the method return type.
+
+```objc
+- (BOOL)doSomethingRiskyAndReturnError:(NSError **)error
+  __attribute__((swift_name("doSomethingRisky()")));
+- (BOOL)doSomethingContrived:(NSString *)action error:(NSError **)outError
+  __attribute__((swift_name("doSomethingContrived(_:error:)")));
+```
+
+```swift
+func doSomethingRisky() throws
+func doSomethingContrived(_ action: String, error: ()) throws
+```
+
+A base name of "init" can be used on a *class* method that returns `instancetype` or the containing static type in order to import that method as an initializer. Any other custom name *prevents* a class method from being imported as an initializer even if it would normally be inferred as one.
+
+```objc
++ (Action *)makeActionWithHandler:(void(^)(void))handler
+  __attribute__((swift_name("init(handler:)")));
++ (instancetype)makeActionWithName:(NSString *)name
+  __attribute__((swift_name("init(name:)")));
+```
+
+```swift
+/* non-inherited */ init(handler: () -> Void)
+init(name: String)
+```
+
+A no-argument method imported as an initializer can be given a dummy argument label to disambiguate it from the no-argument `init()`, whether the method is an init-family instance method or a factory class method in Objective-C.
+
+```objc
+- (instancetype)initSafely
+  __attribute__((swift_name("init(safe:)")));
++ (instancetype)makeDefaultAction
+  __attribute__((swift_name("init(default:)")));
+```
+
+```swift
+init(safe: ())
+init(default: ())
+```
+
+A custom name on an instance method with one of Objective-C's subscript selectors (`objectAtIndexedSubscript:`, `objectForKeyedSubscript:`, `setObject:atIndexedSubscript:`, or `setObject:forKeyedSubscript:`) prevents that method from being imported as a subscript or used as the accessor for another subscript.
+
+_Currently, this only works if *both* methods in a read/write subscript are given custom names; if just one is, a read/write subscript will still be formed. A read-only subscript only has one method to rename._
+
+
 ## More to come...

trunk/docs/WindowsBuild.md

@@ -186,13 +186,11 @@ cmake -G "Visual Studio 2017" -A x64 -T "host=x64"^ ...
 md "S:\b\lldb"
 cd "S:\b\lldb"
 cmake -G Ninja^
+  -DLLVM_DIR="S:/b/llvm/lib/cmake/llvm"^
+  -DClang_DIR="S:/b/llvm/lib/cmake/clang"^
+  -DSwift_DIR="S:/b/swift/lib/cmake/swift"^
   -DCMAKE_BUILD_TYPE=RelWithDebInfo^
   -DLLDB_ALLOW_STATIC_BINDINGS=YES^
-  -DLLDB_PATH_TO_CLANG_SOURCE="S:\clang"^
-  -DLLDB_PATH_TO_SWIFT_SOURCE="S:\swift"^
-  -DLLDB_PATH_TO_CLANG_BUILD="S:\b\llvm"^
-  -DLLDB_PATH_TO_LLVM_BUILD="S:\b\llvm"^
-  -DLLDB_PATH_TO_SWIFT_BUILD="S:\b\swift"^
   -DLLVM_ENABLE_ASSERTIONS=ON^
   -DPYTHON_HOME="%ProgramFiles(x86)%\Microsoft Visual Studio\Shared\Python37_64"^
   S:\lldb

trunk/include/swift/AST/DiagnosticConsumer.h

@@ -38,10 +38,17 @@ enum class DiagnosticKind : uint8_t {
   Note
 };
 
-/// Extra information carried along with a diagnostic, which may or
-/// may not be of interest to a given diagnostic consumer.
+/// Information about a diagnostic passed to DiagnosticConsumers.
 struct DiagnosticInfo {
   DiagID ID = DiagID(0);
+  SourceLoc Loc;
+  DiagnosticKind Kind;
+  StringRef FormatString;
+  ArrayRef<DiagnosticArgument> FormatArgs;
+  SourceLoc BufferIndirectlyCausingDiagnostic;
+
+  /// DiagnosticInfo of notes which are children of this diagnostic, if any
+  ArrayRef<DiagnosticInfo *> ChildDiagnosticInfo;
 
   /// Represents a fix-it, a replacement of one range of text with another.
   class FixIt {
@@ -60,6 +67,24 @@ struct DiagnosticInfo {
 
   /// Extra source ranges that are attached to the diagnostic.
   ArrayRef<FixIt> FixIts;
+
+  /// This is a note which has a parent error or warning
+  bool IsChildNote = false;
+
+  DiagnosticInfo() {}
+
+  DiagnosticInfo(DiagID ID, SourceLoc Loc, DiagnosticKind Kind,
+                 StringRef FormatString,
+                 ArrayRef<DiagnosticArgument> FormatArgs,
+                 SourceLoc BufferIndirectlyCausingDiagnostic,
+                 ArrayRef<DiagnosticInfo *> ChildDiagnosticInfo,
+                 ArrayRef<CharSourceRange> Ranges, ArrayRef<FixIt> FixIts,
+                 bool IsChildNote)
+      : ID(ID), Loc(Loc), Kind(Kind), FormatString(FormatString),
+        FormatArgs(FormatArgs),
+        BufferIndirectlyCausingDiagnostic(BufferIndirectlyCausingDiagnostic),
+        ChildDiagnosticInfo(ChildDiagnosticInfo), Ranges(Ranges),
+        FixIts(FixIts), IsChildNote(IsChildNote) {}
 };
 
 /// Abstract interface for classes that present diagnostics to the user.

trunk/include/swift/AST/DiagnosticEngine.h

@@ -337,7 +337,9 @@ namespace swift {
     SmallVector<DiagnosticArgument, 3> Args;
     SmallVector<CharSourceRange, 2> Ranges;
     SmallVector<FixIt, 2> FixIts;
+    std::vector<Diagnostic> ChildNotes;
     SourceLoc Loc;
+    bool IsChildNote = false;
     const Decl *Decl = nullptr;
 
     friend DiagnosticEngine;
@@ -362,10 +364,13 @@ namespace swift {
     ArrayRef<DiagnosticArgument> getArgs() const { return Args; }
     ArrayRef<CharSourceRange> getRanges() const { return Ranges; }
     ArrayRef<FixIt> getFixIts() const { return FixIts; }
+    ArrayRef<Diagnostic> getChildNotes() const { return ChildNotes; }
+    bool isChildNote() const { return IsChildNote; }
     SourceLoc getLoc() const { return Loc; }
     const class Decl *getDecl() const { return Decl; }
 
     void setLoc(SourceLoc loc) { Loc = loc; }
+    void setIsChildNote(bool isChildNote) { IsChildNote = isChildNote; }
     void setDecl(const class Decl *decl) { Decl = decl; }
 
     /// Returns true if this object represents a particular diagnostic.
@@ -386,6 +391,8 @@ namespace swift {
     void addFixIt(FixIt &&F) {
       FixIts.push_back(std::move(F));
     }
+
+    void addChildNote(Diagnostic &&D);
   };
 
   /// Describes an in-flight diagnostic, which is currently active
@@ -665,7 +672,8 @@ namespace swift {
 
     friend class InFlightDiagnostic;
     friend class DiagnosticTransaction;
-    
+    friend class CompoundDiagnosticTransaction;
+
   public:
     explicit DiagnosticEngine(SourceManager &SourceMgr)
         : SourceMgr(SourceMgr), ActiveDiagnostic(),
@@ -878,6 +886,15 @@ namespace swift {
       return diagnose(decl, Diagnostic(id, std::move(args)...));
     }
 
+    /// Emit a parent diagnostic and attached notes.
+    ///
+    /// \param parentDiag An InFlightDiagnostic representing the parent diag.
+    ///
+    /// \param builder A closure which builds and emits notes to be attached to
+    /// the parent diag.
+    void diagnoseWithNotes(InFlightDiagnostic parentDiag,
+                           llvm::function_ref<void(void)> builder);
+
     /// \returns true if diagnostic is marked with PointsToFirstBadToken
     /// option.
     bool isDiagnosticPointsToFirstBadToken(DiagID id) const;
@@ -905,6 +922,10 @@ namespace swift {
     /// Retrieve the active diagnostic.
     Diagnostic &getActiveDiagnostic() { return *ActiveDiagnostic; }
 
+    /// Generate DiagnosticInfo for a Diagnostic to be passed to consumers.
+    Optional<DiagnosticInfo>
+    diagnosticInfoForDiagnostic(const Diagnostic &diagnostic);
+
     /// Send \c diag to all diagnostic consumers.
     void emitDiagnostic(const Diagnostic &diag);
 
@@ -945,6 +966,7 @@ namespace swift {
   /// in LIFO order. An open transaction is implicitly committed upon
   /// destruction.
   class DiagnosticTransaction {
+  protected:
     DiagnosticEngine &Engine;
 
     /// How many tentative diagnostics there were when the transaction
@@ -968,7 +990,6 @@ namespace swift {
         Depth(Engine.TransactionCount),
         IsOpen(true)
     {
-      assert(!Engine.ActiveDiagnostic);
       Engine.TransactionCount++;
     }
 
@@ -1011,6 +1032,61 @@ namespace swift {
              "transactions must be closed LIFO");
     }
   };
+
+  /// Represents a diagnostic transaction which constructs a compound diagnostic
+  /// from any diagnostics emitted inside. A compound diagnostic consists of a
+  /// parent error, warning, or remark followed by a variable number of child
+  /// notes. The semantics are otherwise the same as a regular
+  /// DiagnosticTransaction.
+  class CompoundDiagnosticTransaction : public DiagnosticTransaction {
+  public:
+    explicit CompoundDiagnosticTransaction(DiagnosticEngine &engine)
+        : DiagnosticTransaction(engine) {}
+
+    ~CompoundDiagnosticTransaction() {
+      if (IsOpen) {
+        commit();
+      }
+
+      if (Depth == 0) {
+        Engine.TransactionStrings.clear();
+        Engine.TransactionAllocator.Reset();
+      }
+    }
+
+    void commit() {
+      assert(PrevDiagnostics < Engine.TentativeDiagnostics.size() &&
+             "CompoundDiagnosticTransaction must contain at least one diag");
+
+      // The first diagnostic is assumed to be the parent. If this is not an
+      // error or warning, we'll assert later when trying to add children.
+      Diagnostic &parent = Engine.TentativeDiagnostics[PrevDiagnostics];
+
+      // Associate the children with the parent.
+      for (auto diag =
+               Engine.TentativeDiagnostics.begin() + PrevDiagnostics + 1;
+           diag != Engine.TentativeDiagnostics.end(); ++diag) {
+        diag->setIsChildNote(true);
+        parent.addChildNote(std::move(*diag));
+      }
+
+      // Erase the children, they'll be emitted alongside their parent.
+      Engine.TentativeDiagnostics.erase(Engine.TentativeDiagnostics.begin() +
+                                            PrevDiagnostics + 1,
+                                        Engine.TentativeDiagnostics.end());
+
+      DiagnosticTransaction::commit();
+    }
+  };
+
+  inline void
+  DiagnosticEngine::diagnoseWithNotes(InFlightDiagnostic parentDiag,
+                                      llvm::function_ref<void(void)> builder) {
+    CompoundDiagnosticTransaction transaction(*this);
+    parentDiag.flush();
+    builder();
+  }
+
 } // end namespace swift
 
 #endif