[docs] Update ObjC documentation so it's visible from GitHub Pages (#213)

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.
 
@@ -13,3 +13,8 @@ It is not possible to have two mono runtimes co-exists inside the same applicati
 
 ## ObjC generated code
 
+### Nullability
+
+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.

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,27 @@ 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`.
+
+### NSObject Protocol support
+
+By default we assume the default hashing and equality of both .net and the ObjC runtime are fine and interchangeable as they share very similar semantics.
+
+When a managed type overrides `Equals(Object)` or `GetHashCode` then it generally means the defaut (.net) behaviour was not the best one. We can assume the default ObjC behaviour would not be either.
+
+In such case the generator overrides the [`isEqual:`](https://developer.apple.com/reference/objectivec/1418956-nsobject/1418795-isequal?language=objc) method and [`hash`](https://developer.apple.com/reference/objectivec/1418956-nsobject/1418859-hash?language=objc) property defined in the [`NSObject` protocol](https://developer.apple.com/reference/objectivec/1418956-nsobject?language=objc). This allows the custom managed implementation to be used from ObjC code transparently.
+
+### Comparison
+
+Managed types that implement `IComparable` or it's generic version `IComparable<T>` will produce ObjC friendly methods that returns a `NSComparisonResult` and accept a `nil` argument. This makes the generated API more friendly to ObjC developers, e.g.
+
+```
+- (NSComparisonResult)compare:(XAMComparableType * _Nullable)other;
+```
+
+
 ## Main differences with .NET
 
 ### Constructors v.s. Initializers

docs/error.md

@@ -1,7 +1,7 @@
-id:{932C3F0C-D968-42D1-BB14-D97C73361983}
+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)
 
@@ -44,6 +44,10 @@ The tool does not support the compilation target `X`. It is possible that anothe
 
 The tool could not find the currently selected Xcode location using the `xcode-select -p` command. Please verify that this command succeeds, and returns the correct Xcode location.
 
+<h3><a name="EM0007"/>EM0007: Could not get the sdk version for '{sdk}'.</h3>
+
+The tool could not get the SDK version using the `xcrun --show-sdk-version --sdk {sdk}` command. Please verify that this command succeeds, and returns the SDK version.
+
 <h3><a name="EM0008"/>EM0008: The architecture '{arch}' is not valid for {platform}. Valid architectures for {platform} are: '{architectures}'.</h3>
 
 The architecture in the error message is not valid for the targeted platform. Please verify that the --abi option is passed a valid architecture.
@@ -52,6 +56,26 @@ The architecture in the error message is not valid for the targeted platform. Pl
 
 This is a known issue that we intend to fix in a future release of the generator. Contributions are welcome.
 
+<h3><a name="EM0010"/>EM0010: Can't merge the frameworks '{simulatorFramework}' and '{deviceFramework}' because the file '{file}' exists in both.</h3>
+
+The tool could not merge the frameworks mentioned in the error message, because there's a common file between them.
+
+This might indicate a bug in the Embeddinator-4000; please file a bug report at [https://github.com/mono/Embeddinator-4000/issues](https://github.com/mono/Embeddinator-4000/issues) with a test case.
+
+<h3><a name="EM0011"/>EM0011: The assembly `X` does not exist.</h3>
+
+The tool could not find the assembly `X` specified in the arguments.
+
+<h3><a name="EM0012"/>EM0012: The assembly name `X` is not unique</h3>
+
+More than one assembly supplied have the same, internal name and it would not be possible to distinguish between them at runtime.
+
+The most likely cause is that an assembly is specified more than once on the command-line arguments. However a renamed assembly still keeps it's original name and multiple copies cannot coexists.
+
+<h3><a name="EM0013"/>EM0013: Can't find the assembly 'X', referenced by 'Y'.</h3>
+
+The tool could not find the assembly 'X', referenced by the assembly 'Y'. Please make sure all referenced assemblies are in the same directory as the assembly to be bound.
+
 <h3><a name="EM0099"/>EM0099: Internal error *. Please file a bug report with a test case (https://github.com/mono/Embeddinator-4000/issues).</h3>
 
 This error message is reported when an internal consistency check in the Embeddinator-4000 fails.
@@ -122,6 +146,11 @@ This is a **warning** that the default parameters of method `M` are not generati
 
 Note: Supported features will evolve with new versions of the tool.
 
+<h3><a name="EM1033"/>Method `M` is not generated because another method exposes the operator with a friendly name.</h3>
+
+This is a **warning** that the method `M` is not generated because another method exposes the operator with a friendly name. (https://msdn.microsoft.com/en-us/library/ms229032(v=vs.110).aspx)
+
+
 
 <h3><a name="EM1040"/>Property `P` is not generated because of parameter type `T` is not supported.</h3>
 
@@ -131,6 +160,19 @@ There should be an earlier warning giving more information why type `T` is not s
 
 Note: Supported features will evolve with new versions of the tool.
 
+<h3><a name="EM1041"/>Indexed properties on `T` is not generated because multiple indexed properties are not supported.</h3>
+
+This is a **warning** that the indexed properties on `T` will be ignored (i.e. nothing will be generated) because multiple indexed properties are not supported.
+
+
+<h3><a name="EM1050"/>Field `F` is not generated because of field type `T` is not supported.</h3>
+
+This is a **warning** that the field `F` will be ignored (i.e. nothing will be generated) because the exposed type `T` is not supported.
+
+There should be an earlier warning giving more information why type `T` is not supported.
+
+Note: Supported features will evolve with new versions of the tool.
+
 
 <!-- 2xxx: code generation -->