Add initial documentation for the projection tooling

[kotlarmilos]

Description

This PR adds initial documentation for the tooling focusing on static methods and P/Invoke declarations.

[jkotas]

The internal constructor won't work well if the bindings are spanning multiple assemblies. I assume that we will eventually want to have one assembly per component for pre-generated bindings.

[kotlarmilos]

What do you consider a component? Should we split them by Swift namespaces?

@stephen-hawley Is there any particular reason the constructor has been set to internal?

[jkoritzinsky]

I would consider each .framework a separate component.

[jkoritzinsky]

Can you add an explanation of what these parameters mean to this doc?

[kotlarmilos]

Here is the current definition:

	[AttributeUsage (AttributeTargets.Class, AllowMultiple = false)]
	public sealed class SwiftStructAttribute : SwiftValueTypeAttribute {

		public SwiftStructAttribute (string libraryName, string nominalTypeDescriptor, string metadata, string witnessTable)
			: base (libraryName, nominalTypeDescriptor, metadata, witnessTable)
		{
		}
	}

It seems to be intended for future extensibility. If that's the case, I would removing it to simplify and narrow the scope.

[vitek-karas]

It would make sense to have a way to identify the Swift type - specifically for the Projection B relies on Projection A scenario - B will need to be able to find which C# type is a specific Swift type from A.

[kotlarmilos]

Is the implemented interface sufficient for identifying the Swift type?

[rolfbjarne]

Any particular reason Roslyn wouldn't work?

[vitek-karas]

I agree with Rolf that we should use Roslyn. But I think it's OK to stick with the existing code for now and change this as a subsequent PR - but Roslyn should be the plan (unless there's some technical reason not to)

[jkotas]

FWIW, Roslyn is not a particularly great API for generating source code. Most source generators generate the source by printing it one line at time, without much help from Roslyn. Random example: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/gen/JsonSourceGenerator.Emitter.cs#L461-L485

[AaronRobinsonMSFT]

Another facet of this that has been mentioned is that source generators aren't the best solution when C# isn't the "source of truth". When the C# is the "source of truth", the source generators are appropriate - see LibraryImport or the COM source generator.

[kotlarmilos]

Added to the list in dotnet/runtime#95633.

[rolfbjarne]

What happens if code modifies the array directly?

var value = new BarInt ();
value.SwiftData [1] = 42;

I'm assuming nothing good... so maybe we should figure out a way to expose this so that users can't shoot themselves in the foot (as easily at least)?

One simple solution might be to mark it as EditorBrowseable.Never.

[kotlarmilos]

Does it need to be a public member?

[jkoritzinsky]

If it needs to be public, could we use ReadOnlySpan or ReadOnlyMemory?

[vitek-karas]

Is there a description somewhere how exactly this works and what is it for?

[kotlarmilos]

According to the docs, it is an interface that represents Swift named value types.

• byte[] SwiftData { get; set } - gets an array of opaque data that represents the swift value type. The size of the array can be found by calling StructMarshal.Marshal.Strideof().

@stephen-hawley Could you please provide additional context on this?

[kotlarmilos]

This PR has been updated to align with the implementation in #2517. The scope has been narrowed to only include static methods and P/Invoke calls.