/// <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)); }