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