Create a doc outlining ownership rules for the ComInterfaceGenerator

[jtschuster]

We've been hitting some issues with ownership and lifetimes in the COM interface generator, so to avoid adding patches to fix issues as we hit them and add complexity, we thought it would be good to outline the rules as simply and generally as we can before making any more changes.

The main premise is that the ownership transfer rules depend on the level of indirection (by value, pointer, pointer to pointer), whether the type is an array or not, and the ownership annotations ([In], [Out], in, out, ref).

[ghost]

Tagging subscribers to this area: @dotnet/interop-contrib
See info in area-owners.md if you want to be subscribed.

Issue Details

---

We've been hitting some issues with ownership and lifetimes in the COM interface generator, so to avoid adding patches to fix issues as we hit them and add complexity, we thought it would be good to outline the rules as simply and generally as we can before making any more changes.

The main premise is that the ownership transfer rules depend on the level of indirection (by value, pointer, pointer to pointer), whether the type is an array or not, and the ownership annotations ([In], [Out], in, out, ref).

Author:	jtschuster
Assignees:	-
Labels:	area-System.Runtime.InteropServices
Milestone:	-

[AaronRobinsonMSFT]

The content here is good. Perhaps there is a more effective way to organize/represent it. Have you considered the pivot being the type and then have examples (both C# and C/C++) for each. Below is a sketch, but note the type, not the indirection, is the primary pivot. Then below it are the ways to pass the type with an example in C# and the same signature in C/C++/IDL. This let's users easily determine the type they are using and then find an example on how it is being used.

## Primitives

### By Value

### By Reference

C# - void Method(ref int a);
COM - HRESULT Method(int* a);

## Array

### By Value - Blittable

C# - void Method(int[] a);
COM - HRESULT Method(int* a);

[danmoseley]

Is this only applicable to this repo or should it go in docs (similar to how we moved our interop doc to make a great public doc)?

[AaronRobinsonMSFT]

Is this only applicable to this repo or should it go in docs (similar to how we moved our interop doc to make a great public doc)?

Excellent suggestion @danmoseley. I think this is in line with the Interop team's focus on improving docs. I think having a page with this content under https://learn.microsoft.com/dotnet/standard/native-interop/cominterop would be most welcome to all.

@jtschuster Thoughts?

[jtschuster]

Is this only applicable to this repo or should it go in docs (similar to how we moved our interop doc to make a great public doc)?

Excellent suggestion @danmoseley. I think this is in line with the Interop team's focus on improving docs. I think having a page with this content under https://learn.microsoft.com/dotnet/standard/native-interop/cominterop would be most welcome to all.

@jtschuster Thoughts?

That's a good idea, I'll make some changes to make it more suitable for public docs.

[jtschuster]

This will be going into public docs instead