/// <summary>
/// Generates the <em><command:inputType></em> element for a pipeline parameter.
/// </summary>
/// <param name="commentReader">Provides access to the XML Doc comments.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="reportWarning">Function used to log warnings.</param>
/// <returns>A <em><command:inputType></em> element for the <paramref name="parameter"/>'s type.</returns>
private XElement GenerateInputTypeElement(ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
var inputTypeDescription = commentReader.GetInputTypeDescriptionElement(parameter, reportWarning);
return new XElement(commandNs + "inputType",
GenerateTypeElement(commentReader, parameter.ParameterType, inputTypeDescription == null, reportWarning),
inputTypeDescription);
}
/// <summary>
/// Fetch the description from the ICommentReader.
/// If the parameter is an Enum, add to the description a list of its legal values.
/// </summary>
private static XElement GenerateDescriptionElement(ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
var descriptionElement = commentReader.GetParameterDescriptionElement(parameter, reportWarning);
if (parameter.EnumValues.Any())
{
if (descriptionElement == null)
{
descriptionElement = new XElement(mamlNs + "description");
}
descriptionElement.Add(
new XElement(mamlNs + "para",
"Possible values: " + string.Join(", ", parameter.EnumValues)));
}
return descriptionElement;
}
/// <summary>
/// Generates a <em><command:parameterValueGroup></em> element for a parameter
/// in order to display enum choices in the cmdlet's syntax section.
/// </summary>
private XElement GetParameterEnumeratedValuesElement(Parameter parameter)
{
var enumValues = parameter.EnumValues.ToList();
if (enumValues.Any())
{
var parameterValueGroupElement = new XElement(commandNs + "parameterValueGroup");
foreach (var enumValue in enumValues)
{
parameterValueGroupElement.Add(GenerateParameterEnumeratedValueElement(enumValue));
}
return parameterValueGroupElement;
}
return null;
}
// Because the proper aliases generated in GenerateParameterElement are not manifested by Get-Help,
// this simply duplicates parameters that have aliases, substituting in the alias name.
// Thus, one could do Get-Help xyz -param actualName or Get-Help xyz -param aliasName
private void GenerateAliasElements(ICommentReader commentReader, ReportWarning reportWarning, Parameter parameter, XElement parametersElement)
{
foreach (var alias in parameter.Aliases)
{
var parameterElement = GenerateParameterElement(commentReader, parameter, ParameterAttribute.AllParameterSets, reportWarning);
parametersElement.Add(parameterElement);
var nameElement = (XElement) (parameterElement.Nodes().First(n => ((XElement) n).Name == mamlNs + "name"));
nameElement.Value = alias;
var descriptionElement = (XElement) (parameterElement.Nodes().FirstOrDefault(n => ((XElement) n).Name == mamlNs + "description"));
if (descriptionElement == null)
{
descriptionElement = new XElement(mamlNs + "description");
parameterElement.Add(descriptionElement);
}
descriptionElement.Add(new XElement(mamlNs + "para", string.Format("This is an alias of the {0} parameter.", parameter.Name)));
}
}
/// <summary>
/// Generates a <em><command:parameter></em> element for a single parameter.
/// </summary>
/// <param name="commentReader">Provides access to the XML Doc comments.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="parameterSetName">The specific parameter set name, or <see cref="ParameterAttribute.AllParameterSets"/>.</param>
/// <param name="reportWarning">Function used to log warnings.</param>
/// <returns>A <em><command:parameter></em> element for the <paramref name="parameter"/>.</returns>
private XElement GenerateParameterElement(ICommentReader commentReader, Parameter parameter, string parameterSetName, ReportWarning reportWarning)
{
var element = new XElement(commandNs + "parameter",
new XAttribute("required", parameter.IsRequired(parameterSetName)),
new XAttribute("globbing", parameter.SupportsGlobbing(parameterSetName)),
new XAttribute("pipelineInput", parameter.GetIsPipelineAttribute(parameterSetName)),
new XAttribute("position", parameter.GetPosition(parameterSetName)),
new XElement(mamlNs + "name", parameter.Name),
GenerateDescriptionElement(commentReader, parameter, reportWarning),
commentReader.GetParameterValueElement(parameter, reportWarning),
GenerateTypeElement(commentReader, parameter.ParameterType, true, reportWarning),
commentReader.GetParameterDefaultValueElement(parameter),
GetParameterEnumeratedValuesElement(parameter));
var aliasNames = parameter.Aliases.ToList();
if (aliasNames.Count > 0)
{
element.Add(new XAttribute("aliases", string.Join(",", aliasNames)));
}
return element;
}
/// <summary>
///
/// </summary>
/// <param name="commentReader">The comment reader.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="reportWarning">Used to record warnings.</param>
/// <returns>A description element for the parameter.</returns>
public static XElement GetParameterValueElement(this ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
return new XElement(CommandNs + "parameterValue",
new XAttribute("required", true),
GetSimpleTypeName(parameter.ParameterType));
}
/// <summary>
/// Obtains a <em><maml:description></em> element for a parameter.
/// </summary>
/// <param name="commentReader">The comment reader.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="reportWarning">Used to record warnings.</param>
/// <returns>A description element for the parameter.</returns>
public static XElement GetParameterDescriptionElement(this ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
var memberInfo = parameter.MemberInfo;
var commentsElement = commentReader.GetComments(memberInfo);
return GetMamlDescriptionElementFromXmlDocComment(commentsElement, "description", warningText => reportWarning(memberInfo, warningText));
}
/// <summary>
/// Obtains a <em><dev:defaultValue></em> element for a parameter.
/// </summary>
/// <param name="commentReader">The comment reader.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="reportWarning">Used to record warnings.</param>
/// <returns>A default value element for the parameter's default value, or <em>null</em> if a default value could not be obtained.</returns>
public static XElement GetParameterDefaultValueElement(this ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
var defaultValue = parameter.GetDefaultValue(reportWarning); // TODO: Get the default value from the doc comments?
if (defaultValue != null)
{
return new XElement(DevNs + "defaultValue", defaultValue.ToString());
}
return null;
}
/// <summary>
/// Obtains a <em><maml:description></em> for an <em><command:inputType></em> coresponding to a specified parameter that accepts pipeline input.
/// </summary>
/// <param name="commentReader">The comment reader.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="reportWarning">Used to log any warnings.</param>
/// <returns>A <em><maml:description></em> for an <em><command:inputType></em> for the parameter, or null if no explicit description is available
/// for the input type.</returns>
public static XElement GetInputTypeDescriptionElement(this ICommentReader commentReader, Parameter parameter, ReportWarning reportWarning)
{
var parameterMemberInfo = parameter.MemberInfo;
var commentsElement = commentReader.GetComments(parameterMemberInfo);
// First try to read the explicit inputType description.
var inputTypeDescription = GetMamlDescriptionElementFromXmlDocComment(commentsElement, "inputType", _ => { });
if (inputTypeDescription != null)
{
return inputTypeDescription;
}
// Then fall back to using the parameter description.
var parameterDescription = commentReader.GetParameterDescriptionElement(parameter, reportWarning);
if (parameterDescription == null)
{
reportWarning(parameterMemberInfo, "No inputType comment found and no fallback description comment found.");
}
return parameterDescription;
}
/// <summary>
/// Generates a <em><command:parameter></em> element for a single parameter.
/// </summary>
/// <param name="commentReader">Provides access to the XML Doc comments.</param>
/// <param name="parameter">The parameter.</param>
/// <param name="parameterSetName">The specific parameter set name, or <see cref="ParameterAttribute.AllParameterSets"/>.</param>
/// <param name="reportWarning">Function used to log warnings.</param>
/// <returns>A <em><command:parameter></em> element for the <paramref name="parameter"/>.</returns>
private XElement GenerateParameterElement(ICommentReader commentReader, Parameter parameter, string parameterSetName, ReportWarning reportWarning)
{
return new XElement(commandNs + "parameter",
new XAttribute("required", parameter.IsRequired(parameterSetName)),
new XAttribute("globbing", parameter.SupportsGlobbing(parameterSetName)),
new XAttribute("pipelineInput", parameter.GetIsPipelineAttribute(parameterSetName)),
new XAttribute("position", parameter.GetPosition(parameterSetName)),
new XElement(mamlNs + "name", parameter.Name),
commentReader.GetParameterDescriptionElement(parameter, reportWarning),
commentReader.GetParameterValueElement(parameter, reportWarning),
GenerateTypeElement(commentReader, parameter.ParameterType, true, reportWarning),
commentReader.GetParameterDefaultValueElement(parameter));
}
