[cxx-interop] Add documentation about calling ctor or static factory of SWIFT_SHARED_REFERENCE types as Swift Initializer #1079
Conversation
fahadnayyar
requested review from
timsneath,
tkremenek,
shahmishal and
davelester
as code owners
…of SWIFT_SHARED_REFERENCE types as Swift Initializer
fahadnayyar
force-pushed
the
cxx-frt-ctor-static-factory-docs
branch
from
b8a4ffc to
d61979c
Compare
| @@ -1239,8 +1239,8 @@ To specify that a C++ type is a shared reference type, use the `SWIFT_SHARED_REF | |||
| class SharedObject : IntrusiveReferenceCounted<SharedObject> { | |||
| public: | |||
| SharedObject(const SharedObject &) = delete; // non-copyable | |||
| SharedObject(); // Constructor | |||
There was a problem hiding this comment.
I think the readers of this document already know that this is a constructor, they probably know basic C++, we don't need this comment.
| @@ -1250,11 +1250,19 @@ void releaseSharedObject(SharedObject *); | |||
|
|
|||
| Now that `SharedObject` is imported as a reference type in Swift, the programmer will be able to use it in the following manner: | |||
| ```swift | |||
| let object = SharedObject.create() | |||
| // Call the C++ constructor of SharedObject using Swift initializer syntax. | |||
| let object = SharedObject() | |||
There was a problem hiding this comment.
I would keep both the create and the initializer example as the static factory method still can express certain things we cannot do using constructors, for example using a custom allocator and taking extra parameters for that allocator.
| @@ -1250,11 +1250,19 @@ void releaseSharedObject(SharedObject *); | |||
|
|
|||
| Now that `SharedObject` is imported as a reference type in Swift, the programmer will be able to use it in the following manner: | |||
| ```swift | |||
| let object = SharedObject.create() | |||
| // Call the C++ constructor of SharedObject using Swift initializer syntax. | |||
There was a problem hiding this comment.
I'd rather have a comment like: The C++ constructor is imported as a Swift initializer. The users can figure out this is an initializer syntax on their own if they know some swift.
| object.doSomething() | ||
| // `object` will be released here. | ||
| ``` | ||
|
|
||
| You can create instances of `SharedObject` directly in Swift by calling its C++ constructor through a Swift initializer. | ||
|
|
||
| Alternatively, you can construct instances using a user-defined static factory function, provided that the factory function is annotated with `SWIFT_NAME("init(...)")`, where the number of `_` placeholders matches the number of parameters in the factory function |
There was a problem hiding this comment.
We should have a code example for this SWIFT_NAME trick. Also we should explain why would the user want to do this (e.g., we don't support custom allocators).
I think it is worth mentioning that we use the default new/delete for allocation/deallocation and if someone wants to disable the importing of ctors as initializers they can delete these operations for their class.
Update C++ interop documentation to describe Swift initializer support for C++
SWIFT_SHARED_REFERENCEtype's constructors and static factories annotated withSWIFT_NAME.