From 091baea403b7a14cb5aea2ec2c340d2d03aeb93d Mon Sep 17 00:00:00 2001
From: Tom Minka <8955276+tminka@users.noreply.github.com>
Date: Thu, 28 Jan 2021 10:26:28 +0000
Subject: [PATCH] Added section on Out and Ref parameters

---
 .gitignore |  3 +++
 README.md  | 30 ++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/.gitignore b/.gitignore
index 80184f7..5688596 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 _site/
 .sass-cache/
 .jekyll-metadata
+
+# Visual Studio cache/options directory
+.vs/
diff --git a/README.md b/README.md
index 3d25450..d1b5f88 100644
--- a/README.md
+++ b/README.md
@@ -255,6 +255,33 @@ someobject.SomeGenericMethod[int](10)
 someobject.SomeGenericMethod[str]("10")
 ```
 
+## Out and Ref parameters
+
+When a managed method has `out` or `ref` parameters, the arguments appear as 
+normal arguments in Python, but the return value of the method is modified.
+There are 3 cases:
+
+1. If the method is `void` and has one `out` or `ref` parameter, the method returns
+the value of that parameter to Python.  For example, if `someobject` has
+a managed method with signature `void SomeMethod1(out arg)`, it is called like so:
+```
+new_arg = someobject.SomeMethod1(arg)
+```
+where the value of `arg` is ignored, but its type is used for overload resolution.
+
+2. If the method is `void` and has multiple `out`/`ref` parameters, the method returns
+a tuple containing the `out`/`ref` parameter values.  For example, if `someobject` has
+a managed method with signature `void SomeMethod2(out arg, ref arg2)`, it is called like so:
+```
+new_arg, new_arg2 = someobject.SomeMethod2(arg, arg2)
+```
+
+3. Otherwise, the method returns a tuple containing the return value followed by the 
+`out`/`ref` parameter values.  For example:
+```
+found, new_value = dictionary.TryGetValue(key, value)
+``` 
+
 ## Delegates And Events
 
 Delegates defined in managed code can be implemented in Python.
@@ -274,6 +301,9 @@ d = AssemblyLoadEventHandler(my_handler)
 AppDomain.CurrentDomain.AssemblyLoad += d
 ```
 
+Delegates with `out` or `ref` parameters can be implemented in Python by
+following the convention described in [Out and Ref parameters].
+
 Multicast delegates can be implemented by adding more callable objects to
 a delegate instance: