From 25cd15c5d1afdd2d22549baaaefbab5d540951c9 Mon Sep 17 00:00:00 2001
From: Chris Hamons <chris.hamons@xamarin.com>
Date: Thu, 4 May 2017 11:21:30 -0500
Subject: [PATCH] Add documentation for operators and subscripting (#255)

---
 docs/BestPracticesObjC.md |  8 +++++
 docs/ObjC.md              | 75 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/docs/BestPracticesObjC.md b/docs/BestPracticesObjC.md
index 7f3a6e5..4574c7a 100644
--- a/docs/BestPracticesObjC.md
+++ b/docs/BestPracticesObjC.md
@@ -125,3 +125,11 @@ In .NET a constructor must either succeed and return a (_hopefully_) valid insta
 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.
+
+## Operators
+
+ObjC does not allow operators to be overloaded as C# does, so these are converted to class selectors. 
+
+["Friendly"](https://msdn.microsoft.com/en-us/library/ms229032(v=vs.110).aspx) named method are generated in preference to the operator overloads when found, and can produce an easier to consume API.
+
+Classes that override the operators == and\or != should override the standard Equals (Object) method as well.
diff --git a/docs/ObjC.md b/docs/ObjC.md
index 5f32714..5f6cdfb 100644
--- a/docs/ObjC.md
+++ b/docs/ObjC.md
@@ -64,6 +64,34 @@ would create an ObjC category like this one:
 
 When a single managed type extends several types then multiple ObjC categories are generated.
 
+### Subscripting
+
+Managed indexed properties are converted into object subscripting. For example:
+
+```
+	public bool this[int index] {
+		get { return c[index]; }
+		set { c[index] = value; }
+	}
+```
+
+would create ObjC similar to :
+
+```
+- (id)objectAtIndexedSubscript:(int)idx;
+- (void)setObject:(id)obj atIndexedSubscript:(int)idx;
+```
+
+which can be used via the ObjC subscripting syntax:
+
+```
+    if ([intCollection [0] isEqual:@42])
+	    intCollection[0] = @13;
+```
+
+Depending on the type of your indexer, indexed or keyed subscripting will be generated where appropriate. 
+
+This [article](http://nshipster.com/object-subscripting/) is a great introduction to subscripting.
 
 ## Main differences with .NET
 
@@ -106,4 +134,49 @@ Objective-C surfaced API:
 @end
 ```
 
-Here we can see that `initWithId:` has been marked as unavailable.
\ No newline at end of file
+Here we can see that `initWithId:` has been marked as unavailable.
+
+### Operator
+
+ObjC does not support operator overloading as C# does, so operators are converted to class selectors:
+
+```
+	public static AllOperators operator + (AllOperators c1, AllOperators c2)
+	{
+		return new AllOperators (c1.Value + c2.Value);
+	}
+```
+
+to
+
+```
++ (instancetype)addition:(Overloads_AllOperators *)anObjectC1 c2:(Overloads_AllOperators *)anObjectC2;
+```
+
+However, some .NET languages do not support operator overloading, so it is common to also include a ["friendly"](https://msdn.microsoft.com/en-us/library/ms229032(v=vs.110).aspx) named method in addition to the operator overload.
+
+If both the operator version and the "friendly" version are found, only the friendly version will be generated.
+
+```
+	public static AllOperatorsWithFriendly operator + (AllOperatorsWithFriendly c1, AllOperatorsWithFriendly c2)
+	{
+		return new AllOperatorsWithFriendly (c1.Value + c2.Value);
+	}
+
+	public static AllOperatorsWithFriendly Add (AllOperatorsWithFriendly c1, AllOperatorsWithFriendly c2)
+	{
+		return new AllOperatorsWithFriendly (c1.Value + c2.Value);
+	}
+```
+
+becomes:
+
+```
++ (instancetype)addC1:(Overloads_AllOperatorsWithFriendly *)anObjectC1 c2:(Overloads_AllOperatorsWithFriendly *)anObjectC2;
+```
+
+### Equality operator
+
+In general operator == in C# is handled as a general operator as noted above.
+
+However, if the "friendly" Equals operator is found, both operator == and operator != will be skipped in generation.