[Doc BUG] [Missing information] Marshalling shapes

[smaillet]

Description

The docs for custom marshalling are sadly lacking on clarity leaving developers EXTREMELY frustrated. As a specific example:
docs/design/libraries/LibraryImportGenerator/UserTypeMarshallingV2.md
List the "shapes" of marshalling (but doesn't define the term OR how these are actually used). Moreover, it routinely mixes its own pseudo templating with actual generic parameters but fails to define ALL such pseudo templated parameters. TOther is a particularly nasty one as there's NOTHING anywhere that describes it - what the heck is it supposed to be?

Reproduction Steps

Try and create a custom marshaller for an array of SafeHandles that just calls DangerousGetHandle() to get the underlying nint. This is perfectly legit thing to do when the caller owns the release of the handle and the native code won't do that (It just uses the handles it is given)

Expected behavior

This should all just work and be WELL documented, so it is easy to implement custom marshalling. As it is, it's just not possible to do - the docs are so steep with insider baseball they are unusable to anyone outside the core dev team. This makes marshalling of custom types WAY harder than it needs to be.

Actual behavior

custom marshalling is unusable as the docs are too vague and include too much insider baseball.

Regression?

No response

Known Workarounds

No response

Configuration

No response

Other information

No response

[dotnet-policy-service]

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

[dotnet-policy-service]

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

[huoyaoyuan]

FWIW, the file UserTypeMarshallingV2.md serves as a design doc: it's for designers and implementations to get aligned about the feature. It's not really a user-faced documentation.

[smaillet]

@huoyaoyuan if it's not meant for public consumption than:

1. it should not be linked to from the public docs
2. There's NO documentation anywhere on the "shape" of marshallers nor how to actually implement one.
   • There are multiple doc topics that describe it as possible but maddeningly, do NOT contain any details on HOW it is all supposed to work

[jkotas]

For reference, these docs are linked from https://learn.microsoft.com/en-us/dotnet/standard/native-interop/custom-marshalling-source-generation#see-also . We should delete the link and replace it with proper public facing docs.