2

So, I have a an action that takes a callback and performs it. It looks a little bit like this. Is there anything I can fill in into the question mark area (or elsewhere) to document the details of the arguments going into the APICall Func parameter?

/// <summary>
/// Opens Authenticated session to servers using ClientSide SDK's, performs action, closes session
/// </summary>
/// <typeparam name="T">The object to be returned from the authenticated action</typeparam>
/// <param name="credentials">Container for username, password</param>
/// <param name="APICall">?????????????????</param>
///
/// ?????????????????????
/// ?????????????????????
/// ?????????????????????
///    
/// <returns>T</returns>
private static T MakeAuthenticatedCall<T> (CredStorage Credentials, Func<string,T> APICALL)
{
   AuthenticationManager.Login(Credentials);
   T APIResult = APICall(AuthenticationManager.SessionID);
   AuthenticationManager.LogOff();

   return APIResult;
}
2
  • What do you mean? Can't you just put it between the <param name="APICall">? Commented Mar 17, 2016 at 15:55
  • @AlexanderDerck I don't think so. I'm looking to describe the "string" and "T" portions of "Func<string,T> APICALL", and don't see any obvious XML bits that would describe them.
    – Sidney
    Commented Mar 17, 2016 at 16:03

1 Answer 1

2

You can define your own delegate to do this, rather than use the built-in Func<T,...> delegate.

Then not only can you give it XML documentation, you can give a more descriptive name to the parameters.

For example:

/// <summary>Makes an API call.</summary>
/// <typeparam name="T">The type returned by the API call.</typeparam>
/// <param name="param">The parameter passed to the API call.</param>
/// <returns>The value returned by the API call.</returns>

public delegate T ApiCall<T>(string param);

Then you would use that instead of Func<string,T> in your method:

private static T MakeAuthenticatedCall<T>(CredStorage Credentials, ApiCall<T> APICALL)
{

This is arguably a much better way of doing it, although at the expense of having to take the extra time to define a special delegate.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.