red-gate / XmlDoc2CmdletDoc

Create cmdlet XML help files from XML doc comments
Other
63 stars 24 forks source link

Inherited Parameter attributes should not be used #34

Open anywherepilot opened 7 years ago

anywherepilot commented 7 years ago

If you have a hierarchy of inheriting classes with virtual and overridden properties, only the ones applied to the overridden property must be taken into account, including none if the overridden property has no such attributes. This is the way PowerShell itself does it. From the PowerShell source CompiledCommandParameter.cs:

// We do not want to get the inherited custom attributes, only the attributes exposed
// directly on the member
var memberAttributes = member.GetCustomAttributes(false);

In our setup we encountered three problems with this:

  1. Parameters which are in AllParameterSets in the base class but only in specific ones in the derived class, are documented as if they are everywhere, while they are not in PowerShell.
  2. Parameters which are mandatory in the base class and not mandatory in the derived class are documented as if they are mandatory, while they are not in PowerShell.
  3. Parameters which are hidden in the derived class by overriding the property without an attribute, are documented as if they exist, while they are not in PowerShell.

    The fix could be as simple as adding 'false' into the calls to GetCustomAttributes, similarly to how PowerShell does it internally. For the Mandatory issue, it may also be necessary to change this code to allow for specific parameter sets to override the value from AllParameterSets:

public bool IsRequired(string parameterSetName)
{
    return GetAttributes(parameterSetName).Any(attr => attr.Mandatory);
}

Thank you for looking into this. Please let me know whether you agree with this analysis and proposed implementation.