[objc][docs] Update (#211)

docs/BestPracticesObjC.md

@@ -1,18 +1,18 @@
 id:{932C3F0C-D968-42D1-BB14-D97C73361983}
 title:Embeddinator-4000 Best Practices for ObjC
 
-[//]: # (The original file resides under https://github.com/mono/Embeddinator-4000/tree/master/docs/BestPracticesObjC.md)
+[//]: # (The original file resides under https://github.com/mono/Embeddinator-4000/tree/objc/docs/BestPracticesObjC.md)
 [//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes)
 [//]: # (Modifications outside of mono/Embeddinator-4000 will be lost on future updates)
 
-This is a draft and might not be in-sync with the features presently supported by the tool. We hope that this document will evolve separately and eventually match the final tool, i.e. we'll suggest the long term best approaches - not immediate workarounds.
+This is a draft and might not be in-sync with the features presently supported by the tool. We hope that this document will evolve separately and eventually match the final tool, i.e. we'll suggest long term best approaches - not immediate workarounds.
 
-A large part of this document also applies to any other supported languages. However all provided examples are in C# and ObjC.
+A large part of this document also applies to other supported languages. However all provided examples are in C# and ObjC.
 
 
 # Exposing a subset of the managed code
 
-The generated native library/framework contains ObjC code to call each of the managed API that is exposed. The more API you surface (public) then larger the native library will become.
+The generated native library/framework contains ObjC code to call each of the managed API that is exposed. The more API you surface (make public) then larger the native _glue_ library will become.
 
 It might be a good idea to create a different, smaller assembly, to expose only the required API to the native developer. That facade will also allow you more control over the visibility, naming, error checking... of the generated code.
 
@@ -117,3 +117,11 @@ public bool TryParse (string number, out int value)
 	return Int32.TryParse (number, out value);
 }
 ```
+
+## Exceptions inside `init*`
+
+In .NET a constructor must either succeed and return a, _hopefully_ valid instance or throw an exception.
+
+In contrast ObjC allows `init*` to return `nil` when an instance cannot be created. This is a common, but not general, pattern used in many of Apple's frameworks. In some other cases an `assert` can happen (and kill the current process).
+
+The generator follow the same `return nil` pattern for generated `init*` methods. If a managed exception is thrown then it will be printed (using `NSLog`) and `nil` will be returned to the caller.

docs/Limitations.md

@@ -4,7 +4,7 @@ This document explains the limitations of **embeddinator-4000** and, whenever po
 
 ## General
 
-### Use more than one embeded libary in a project
+### Use more than one embedded library in a project
 
 It is not possible to have two mono runtimes co-exists inside the same application. This means you cannot use two different, embeddinator-4000-generated libaries inside the same application.
 
@@ -17,4 +17,4 @@ It is not possible to have two mono runtimes co-exists inside the same applicati
 
 There is no metadata, in .NET, that tell us if a null reference is acceptable or not for an API. Most API will throw `ArgumentNullException` if they cannot cope with a `null` argument. This is problematic as ObjC handling of exceptions is something better avoided.
 
-Since we cannot generate accurate nullability annotations in the header files and wish to minimize  managed exceptions we default to non-null arguments (`NS_ASSUME_NONNULL_BEGIN`) and add some specific, when precision is possible, nullability annotations.
+Since we cannot generate accurate nullability annotations in the header files and wish to minimize managed exceptions we default to non-null arguments (`NS_ASSUME_NONNULL_BEGIN`) and add some specific, when precision is possible, nullability annotations.

docs/ObjC.md

@@ -1,3 +1,10 @@
+id:{8e48fb46-9a13-4a1b-a8af-9fe87458a293}
+title:ObjC Support
+
+[//]: # (The original file resides under https://github.com/mono/Embeddinator-4000/tree/objc/docs/ObjC.md)
+[//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes)
+[//]: # (Modifications outside of mono/Embeddinator-4000 will be lost on future updates)
+
 # ObjC
 
 ## Specific features
@@ -12,6 +19,11 @@ The use of Automatic Reference Counting (ARC) is **required** to call the genera
 
 API that expose `System.String` types are converted into `NSString`. This makes memory management easier than dealing with `char*`.
 
+### Protocols support
+
+Managed interfaces are converted into ObjC protocols where all members are `@required`.
+
+
 ## Main differences with .NET
 
 ### Constructors v.s. Initializers

docs/error.md

@@ -1,7 +1,7 @@
 id:{932C3F0C-D968-42D1-BB14-D97C73361983}
 title:Embeddinator-4000 errors
 
-[//]: # (The original file resides under https://github.com/mono/Embeddinator-4000/tree/master/docs/error.md)
+[//]: # (The original file resides under https://github.com/mono/Embeddinator-4000/tree/objc/docs/error.md)
 [//]: # (This allows all contributors (including external) to submit, using a PR, updates to the documentation that match the tools changes)
 [//]: # (Modifications outside of mono/Embeddinator-4000 will be lost on future updates)