Add documentation for RCW marshalling

[Sergio Pedri (Sergio0694)]

Summary

Adds docs/rcw-marshalling.md, a conceptual guide to how CsWinRT 3.0 creates RCWs when marshalling native Windows Runtime objects to managed, and links it from the existing COM interop guide.

Note

This targets #2511 rather than staging/3.0, because the documentation describes the re-entrancy behaviour as fixed by that PR. It should be merged after it.

Motivation

Nothing currently documents the decision logic in WindowsRuntimeComWrappers.CreateObject, which is the part people most often ask about: why a native object sometimes comes back as a fully typed projection and sometimes as an opaque wrapper, when GetRuntimeClassName is consulted, and how the answer depends on the static type at the callsite. The logic is well commented in the source, but those comments are spread across several files and assume a lot of surrounding context.

This came out of exactly that question being asked, and is written to be shareable with people who want to understand the model without reading the implementation.

Changes

• docs/rcw-marshalling.md: new document covering the marshaller entry points and which of the two static callbacks each one supplies (including the fact that ordinary generated non-generic interfaces go through the callback-free entry point, while generic instantiations and selected manually-projected interfaces have callbacks); the CCW unwrap fast path and the existing-wrapper cache hit, which short-circuit the ladder entirely; the decision ladder itself as a Mermaid diagram plus a walkthrough of each rung; when GetRuntimeClassName is and is not called and what its result is used for; how the infrastructure behaves for missing, unrecognised and wrong runtime class names; and four worked scenarios.

• docs/interop.md: link to the new document from the "Create RCW" section.

Notes

The resilience section deliberately separates two cases that are easy to conflate. Names we cannot resolve always degrade safely, costing specialization rather than correctness. Names we can resolve are trusted, so a native object reporting a wrong but known runtime class name can throw or yield an unexpected type — which is precisely why TryCreateObject is consulted before the type map, and why the IStringable / Windows.Foundation.Uri override exists.

The document is documentation only and does not change any behaviour.

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.