I've been working on improving the support for XML doc comment queries with metadata types, but came across some limitations in the reflection API that have hindered my progress. Specifically, I've been trying to add support for retrieving doc comments for methods containing a function pointer as a parameter, and methods containing a parameter that has been decorated with an optional or required custom modifier. Unfortunately, given the current state of the reflection API (for which I will elaborate upon below), I don't believe that I can implement these features and achieve a general solution that works for all inputs.
The goal of this feature is to be able to retrieve the XML comments as given in the following code example.
public ref class T
{
public:
/// <summary/>
/// <param name="param">A function pointer of managed types</param>
void FnPtrMethod(String^ (*param)(TimeSpan, DateTime, array<int>^)) { }
};
Since a function pointer is a native C++ entity, it is not recognized by the CLR and consequently I don't believe it to be possible to adequately represent it with a metadata object. Given the method FnPtrMethod above, the managed type of its sole parameter param is rendered by the reflection API as System.IntPtr. This is understandable sense since the function pointer is really a raw native pointer to the address of executable code. It makes no difference that its arguments are managed types, since the type that encompasses them is not managed. If all we have to work with is an IntPtr instance, then it is impossible to infer that the IntPtr is really a function pointer and fetch its managed arguments for processing.
I'm fairly confident that my analysis is correct, but in the hope of being wrong I've started a discussion on StackOverflow just to be sure. If you know the trick to get this to work, please respond to this blog entry or to the discussion on StackOverflow.
The goal of this feature is to be able to retrieve the XML comments as given in the following code example.
public ref class T
{
public:
/// <summary/>
/// <param name="x">modopt</param>
/// <param name="y">modreq</param>
void modifiers(const int x, volatile int y) { }
};
This feature may be implemented, but only for a small number of variations in the types of method parameters. The problem lies in the placement of the ParameterInfo.GetOptionalCustomModifiers() and ParameterInfo.GetRequiredCustomModifiers() methods. These methods are specific to a parameter, and I believe that they should be generalized and applied to any instance of System.Type. For instance, consider the following method.
public ref class C
{
public:
/// <summary/>
/// <param name="param">Generic action containing modreq/modopt generic argument.</param>
generic <typename T>
void f(Action<const volatile T>^ param) { }
};
The sole parameter param of function f does not have a custom modifier, however the generic method argument T that participates in the definition of the parameter type does. In this case, it doesn't make sense to call param.GetOptionalCustomModifiers() since the modifiers apply to T. To get the metadata for T, we need to call GetGenericArguments() resulting in a System.Type array. But, System.Type does not provide a means to get its custom modifiers! A similar problem also exists with array and pointer types as custom modifiers are applied to the element type of these entities. We need to call GetElementType() on the array/pointer type, but are again presented with a System.Type instance and with no way to get its custom modifiers.
Regarding this issue, I've opened a bug report with Microsoft in hopes that the API flaw will be addressed in a future version of the .NET Framework.
However, all is not lost. We can still use the ParameterInfo.GetOptionalCustomModifiers() and ParameterInfo.GetRequiredCustomModifiers() methods to get custom modifiers for a parameter that is not an array, pointer, or decorated with the by-ref/out attributes (all of these types require us to call GetElementType() to get the type to which the modifier is applied). Also, the parameter can not be dependent on a generic method or type parameter having a custom modifier applied to it. This will at least expose the feature to a small number of methods, but it clearly won't work in the general case. Consequently, I've decided to postpone implementing this feature until I get clearer direction from the community. If you would like to see this feature implement in Jolt.NET, please vote it up on the Jolt.NET CodePlex web site.
