/// <summary> /// Obtains a <em><command:examples></em> element for a cmdlet's examples. /// </summary> /// <param name="commentReader">The comment reader.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Used to log any warnings.</param> /// <returns>An examples element for the cmdlet.</returns> public static XElement GetCommandExamplesElement(this ICommentReader commentReader, Command command, ReportWarning reportWarning) { var cmdletType = command.CmdletType; var comments = commentReader.GetComments(cmdletType); if (comments == null) { reportWarning(cmdletType, "No XML doc comment found."); return null; } var xmlDocExamples = comments.XPathSelectElements("//example").ToList(); if (!xmlDocExamples.Any()) { reportWarning(cmdletType, "No examples found."); return null; } var examples = new XElement(commandNs + "examples"); int exampleNumber = 1; foreach (var xmlDocExample in xmlDocExamples) { var example = GetCommandExampleElement(xmlDocExample, exampleNumber, warningText => reportWarning(cmdletType, warningText)); if (example != null) { examples.Add(example); exampleNumber++; } } return exampleNumber == 1 ? null : examples; }
/// <summary> /// Obtains a <em><maml:alertSet></em> element for a cmdlet's notes. /// </summary> /// <param name="commentReader">The comment reader.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Used to log any warnings.</param> /// <returns>A <em><maml:alertSet></em> element for the cmdlet's notes.</returns> public static XElement GetCommandAlertSetElement(this ICommentReader commentReader, Command command, ReportWarning reportWarning) { var cmdletType = command.CmdletType; var comments = commentReader.GetComments(cmdletType); if (comments == null) { return null; } // First see if there's an alertSet element in the comments var alertSet = comments.XPathSelectElement("//maml:alertSet", Resolver); if (alertSet != null) { return alertSet; } // Next, search for a list element of type <em>alertSet</em>. var list = comments.XPathSelectElement("//list[@type='alertSet']"); if (list == null) { return null; } alertSet = new XElement(MamlNs + "alertSet"); foreach (var item in list.XPathSelectElements("item")) { var term = item.XPathSelectElement("term"); var description = item.XPathSelectElement("description"); if (term != null && description != null) { var alertTitle = new XElement(MamlNs + "title", Tidy(term.Value)); var alert = new XElement(MamlNs + "alert"); var paras = description.XPathSelectElements("para").ToList(); if (paras.Any()) { paras.ForEach(para => alert.Add(new XElement(MamlNs + "para", Tidy(para.Value)))); } else { alert.Add(new XElement(MamlNs + "para", Tidy(description.Value))); } alertSet.Add(alertTitle, alert); } } return alertSet; }
/// <summary> /// Generates the <em><maml:alertSet></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><maml:alertSet></em> element for the <paramref name="command"/>.</returns> private XElement GenerateAlertSetElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return commentReader.GetCommandAlertSetElement(command, reportWarning); }
/// <summary> /// Generates the <em><command:returnValues></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:returnValues></em> element for the <paramref name="command"/>.</returns> private XElement GenerateReturnValuesElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { var returnValueElement = new XElement(commandNs + "returnValues"); foreach (var type in command.OutputTypes) { returnValueElement.Add(GenerateComment("OutputType: " + type.Name)); var returnValueDescription = commentReader.GetOutputTypeDescriptionElement(command, type, reportWarning); returnValueElement.Add(new XElement(commandNs + "returnValue", GenerateTypeElement(commentReader, type, returnValueDescription == null, reportWarning), returnValueDescription)); } return returnValueElement; }
/// <summary> /// Generates the <em><command:inputTypes></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:inputTypes></em> element for the <paramref name="command"/>.</returns> private XElement GenerateInputTypesElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { var inputTypesElement = new XElement(commandNs + "inputTypes"); var pipelineParameters = command.GetParameters(ParameterAttribute.AllParameterSets) .Where(p => p.IsPipeline(ParameterAttribute.AllParameterSets)); foreach (var parameter in pipelineParameters) { inputTypesElement.Add(GenerateInputTypeElement(commentReader, parameter, reportWarning)); } return inputTypesElement; }
/// <summary> /// Generates the <em><command:parameters></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:parameters></em> element for the <paramref name="command"/>.</returns> private XElement GenerateParametersElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { var parametersElement = new XElement(commandNs + "parameters"); foreach (var parameter in command.Parameters) { parametersElement.Add(GenerateComment("Parameter: " + parameter.Name)); parametersElement.Add(GenerateParameterElement(commentReader, parameter, ParameterAttribute.AllParameterSets, reportWarning)); GenerateAliasElements(commentReader, reportWarning, parameter, parametersElement); } return parametersElement; }
/// <summary> /// Generates the <em><command:syntaxItem></em> element for a specific parameter set of a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="parameterSetName">The parameter set name.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:syntaxItem></em> element for the specific <paramref name="parameterSetName"/> of the <paramref name="command"/>.</returns> private XElement GenerateSyntaxItemElement(ICommentReader commentReader, Command command, string parameterSetName, ReportWarning reportWarning) { var syntaxItemElement = new XElement(commandNs + "syntaxItem", new XElement(mamlNs + "name", command.Name)); foreach (var parameter in command.GetParameters(parameterSetName)) { syntaxItemElement.Add(GenerateComment("Parameter: " + parameter.Name)); syntaxItemElement.Add(GenerateParameterElement(commentReader, parameter, parameterSetName, reportWarning)); } return syntaxItemElement; }
/// <summary> /// Generates the <em><command:syntax></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:syntax></em> element for the <paramref name="command"/>.</returns> private XElement GenerateSyntaxElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { var syntaxElement = new XElement(commandNs + "syntax"); IEnumerable<string> parameterSetNames = command.ParameterSetNames.ToList(); if (parameterSetNames.Count() > 1) { parameterSetNames = parameterSetNames.Where(name => name != ParameterAttribute.AllParameterSets); } foreach (var parameterSetName in parameterSetNames) { syntaxElement.Add(GenerateComment("Parameter set: " + parameterSetName)); syntaxElement.Add(GenerateSyntaxItemElement(commentReader, command, parameterSetName, reportWarning)); } return syntaxElement; }
/// <summary> /// Generates the <em><command:details></em> element for a command. /// </summary> /// <param name="commentReader"></param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:details></em> element for the <paramref name="command"/>.</returns> private XElement GenerateDetailsElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return new XElement(commandNs + "details", new XElement(commandNs + "name", command.Name), new XElement(commandNs + "verb", command.Verb), new XElement(commandNs + "noun", command.Noun), commentReader.GetCommandSynopsisElement(command, reportWarning)); }
/// <summary> /// Generates a <em><command:command></em> element for the specified command. /// </summary> /// <param name="commentReader"></param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:command></em> element that represents the <paramref name="command"/>.</returns> private XElement GenerateCommandElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return new XElement(commandNs + "command", new XAttribute(XNamespace.Xmlns + "maml", mamlNs), new XAttribute(XNamespace.Xmlns + "command", commandNs), new XAttribute(XNamespace.Xmlns + "dev", devNs), GenerateDetailsElement(commentReader, command, reportWarning), GenerateDescriptionElement(commentReader, command, reportWarning), GenerateSyntaxElement(commentReader, command, reportWarning), GenerateParametersElement(commentReader, command, reportWarning), GenerateInputTypesElement(commentReader, command, reportWarning), GenerateReturnValuesElement(commentReader, command, reportWarning), GenerateAlertSetElement(commentReader, command, reportWarning), GenerateExamplesElement(commentReader, command, reportWarning), GenerateRelatedLinksElement(commentReader, command, reportWarning)); }
/// <summary> /// Obtains a <em><maml:description></em> for a command's output type. /// </summary> /// <param name="commentReader">The comment reader.</param> /// <param name="command">The command.</param> /// <param name="outputType">The output type of the command.</param> /// <param name="reportWarning">Used to log any warnings.</param> /// <returns>A <em><maml:description></em> for the command's output type, /// or null if no explicit description is available for the output type.</returns> public static XElement GetOutputTypeDescriptionElement(this ICommentReader commentReader, Command command, Type outputType, ReportWarning reportWarning) { // TODO: Get the description from the <remarks type="outputType" cref="<type>"> element return commentReader.GetTypeDescriptionElement(outputType, reportWarning); }
/// <summary> /// Obtains a <em><maml:description></em> element for a cmdlet's synopsis. /// </summary> /// <param name="commentReader">The comment reader.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Used to record warnings.</param> /// <returns>A description element for the cmdlet's synopsis.</returns> public static XElement GetCommandSynopsisElement(this ICommentReader commentReader, Command command, ReportWarning reportWarning) { var cmdletType = command.CmdletType; var commentsElement = commentReader.GetComments(cmdletType); return GetMamlDescriptionElementFromXmlDocComment(commentsElement, "synopsis", warningText => reportWarning(cmdletType, warningText)); }
/// <summary> /// Obtains a <em><command:relatedLinks></em> element for a cmdlet's related links. /// </summary> /// <param name="commentReader">The comment reader.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Used to log any warnings.</param> /// <returns>An relatedLinks element for the cmdlet.</returns> public static XElement GetCommandRelatedLinksElement(this ICommentReader commentReader, Command command, ReportWarning reportWarning) { var cmdletType = command.CmdletType; var comments = commentReader.GetComments(cmdletType); if (comments == null) { return null; } var paras = comments.XPathSelectElements("//para[@type='link']").ToList(); if (!paras.Any()) return null; var relatedLinks = new XElement(MamlNs + "relatedLinks"); foreach (var para in paras) { var navigationLink = new XElement(MamlNs + "navigationLink", new XElement(MamlNs + "linkText", para.Value)); var uri = para.Attribute("uri"); if (uri != null) { navigationLink.Add(new XElement(MamlNs + "uri", uri.Value)); } relatedLinks.Add(navigationLink); } return relatedLinks; }
/// <summary> /// Generates the <em><command:examples></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:examples></em> element for the <paramref name="command"/>.</returns> private XElement GenerateExamplesElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return commentReader.GetCommandExamplesElement(command, reportWarning); }
/// <summary> /// Generates the <em><maml:description></em> element for a command. /// </summary> /// <param name="commentReader"></param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><maml:description></em> element for the <paramref name="command"/>.</returns> private XElement GenerateDescriptionElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return commentReader.GetCommandDescriptionElement(command, reportWarning); }
/// <summary> /// Generates the <em><maml:relatedLinks></em> element for a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><maml:relatedLinks></em> element for the <paramref name="command"/>.</returns> private XElement GenerateRelatedLinksElement(ICommentReader commentReader, Command command, ReportWarning reportWarning) { return commentReader.GetCommandRelatedLinksElement(command, reportWarning); }
/// <summary> /// Generates the <em><command:syntaxItem></em> element for a specific parameter set of a command. /// </summary> /// <param name="commentReader">Provides access to the XML Doc comments.</param> /// <param name="command">The command.</param> /// <param name="parameterSetName">The parameter set name.</param> /// <param name="reportWarning">Function used to log warnings.</param> /// <returns>A <em><command:syntaxItem></em> element for the specific <paramref name="parameterSetName"/> of the <paramref name="command"/>.</returns> private XElement GenerateSyntaxItemElement(ICommentReader commentReader, Command command, string parameterSetName, ReportWarning reportWarning) { var syntaxItemElement = new XElement(CommandNs + "syntaxItem", new XElement(MamlNs + "name", command.Name)); foreach (var parameter in command.GetParameters(parameterSetName).OrderBy(p => p.GetPosition(parameterSetName)). ThenBy(p => p.IsRequired(parameterSetName) ? "0" : "1"). ThenBy(p => p.Name)) { syntaxItemElement.Add(GenerateComment("Parameter: " + parameter.Name)); syntaxItemElement.Add(GenerateParameterElement(commentReader, parameter, parameterSetName, reportWarning)); } return syntaxItemElement; }