/// <summary>
/// Extract the examples for a Cmdlet parameter.
/// </summary>
/// <param name="cmdletType">
/// The CLR type that implements the Cmdlet.
/// </param>
/// <returns>
/// A list of example, which may be empty.
/// </returns>
public List <CommandExample> GetCmdletExamples(TypeInfo cmdletType)
{
if (cmdletType == null)
{
throw new ArgumentNullException(nameof(cmdletType));
}
var attributes = cmdletType.GetCustomAttributes <CmdletExampleAttribute>();
if (attributes == null)
{
return(null);
}
var examples = new List <CommandExample>();
foreach (var attribute in attributes)
{
examples.Add(
new CommandExample
{
Title = attribute.Title,
Description = MamlGenerator.ToParagraphs(attribute.Description),
Code = attribute.Code,
Remarks = MamlGenerator.ToParagraphs(attribute.Remarks)
}
);
}
return(examples);
}
/// <summary>
/// Extract the description for a Cmdlet parameter.
/// </summary>
/// <param name="parameterProperty">
/// The property that represents the parameter.
/// </param>
/// <returns>
/// The description, or <c>null</c> if no description could be extracted by this extractor.
///
/// An empty list means a description was extracted, but the description is empty (this is legal).
/// </returns>
public List <string> GetParameterDescription(PropertyInfo parameterProperty)
{
if (parameterProperty == null)
{
throw new ArgumentNullException(nameof(parameterProperty));
}
var assemblyDoc = GetAssemblyDocumentation(parameterProperty);
if (assemblyDoc == null)
{
return(null);
}
return(MamlGenerator.ToParagraphs(assemblyDoc.GetSummary(parameterProperty)));
}
/// <summary>
/// Extract the description for a Cmdlet parameter.
/// </summary>
/// <param name="parameterProperty">
/// The property that represents the parameter.
/// </param>
/// <returns>
/// The description, or <c>null</c> if no description could be extracted by this extractor.
///
/// An empty list means a description was extracted, but the description is empty (this is legal).
/// </returns>
public List <string> GetParameterDescription(PropertyInfo parameterProperty)
{
if (parameterProperty == null)
{
throw new ArgumentNullException(nameof(parameterProperty));
}
var descriptionAttribute = parameterProperty.GetCustomAttributes <ParameterAttribute>().Last();
if (descriptionAttribute == null)
{
return(null);
}
// TODO: Handle resource-based messages (with locale).
return(MamlGenerator.ToParagraphs(descriptionAttribute.HelpMessage?.Trim()));
}
/// <summary>
/// Extract the input types for a Cmdlet.
/// </summary>
/// <param name="cmdletType">
/// The CLR type that implements the Cmdlet.
/// </param>
/// <returns>
/// A list of values, which may be empty or null.
/// </returns>
public List <CommandValue> GetCmdletInputTypes(TypeInfo cmdletType)
{
if (cmdletType == null)
{
throw new ArgumentNullException(nameof(cmdletType));
}
var assemblyDoc = GetAssemblyDocumentation(cmdletType);
if (assemblyDoc == null)
{
return(null);
}
var inputElements = assemblyDoc.GetInputs(cmdletType);
var inputTypes = new List <CommandValue>();
foreach (var element in inputElements)
{
var see = element.Element("sees");
var paras = element.Elements("para")?.Select(e => MamlGenerator.ToParagraphs(e?.Value?.Trim())).ToList() ?? new List <List <string> >();
var description = new List <string>();
if (see == null && paras.Count == 0)
{
description.AddRange(MamlGenerator.ToParagraphs(element.Value?.Trim()));
}
else
{
foreach (var list in paras)
{
description.AddRange(list);
}
}
if (see == null || !see.HasAttributes)
{
var first = description[0];
description.RemoveAt(0);
element.Add(
new CommandValue
{
DataType = { Name = first },
Description = description
}
);
continue;
}
var name = see.Attribute("cref")?.Value?.Trim() ?? string.Empty;
if (name != null)
{
try {
var type = Type.GetType(name);
if (type != null)
{
name = MamlGenerator.PowerShellIfyTypeName(type);
}
} catch (ArgumentException)
{
// Ignore this exception
} catch (TypeLoadException)
{
// Ignore this exception
}
}
element.Add(
new CommandValue
{
DataType =
{
Name = name ?? string.Empty,
Uri = see.Attribute("uri")?.Value?.Trim(),
Description = MamlGenerator.ToParagraphs(see.Value?.Trim())
},
Description = description
}
);
}
return(inputTypes);
}
/// <summary>
/// Extract the return values for a Cmdlet.
/// </summary>
/// <param name="cmdletType">
/// The CLR type that implements the Cmdlet.
/// </param>
/// <returns>
/// A list of values, which may be empty or null.
/// </returns>
public List <CommandValue> GetCmdletReturnValues(TypeInfo cmdletType)
{
if (cmdletType == null)
{
throw new ArgumentNullException(nameof(cmdletType));
}
var assemblyDoc = GetAssemblyDocumentation(cmdletType);
if (assemblyDoc == null)
{
return(null);
}
var returnElements = assemblyDoc.GetReturns(cmdletType);
var returnValues = new List <CommandValue>();
foreach (var returnElement in returnElements)
{
var see = returnElement.Element("sees");
var paras = returnElement.Elements("para")?.Select(e => MamlGenerator.ToParagraphs(e?.Value?.Trim())).ToList() ?? new List <List <string> >();
var description = new List <string>();
if (see == null && paras.Count == 0)
{
description.AddRange(MamlGenerator.ToParagraphs(returnElement.Value?.Trim()));
}
else
{
foreach (var list in paras)
{
description.AddRange(list);
}
}
if (see == null || !see.HasAttributes)
{
var first = description[0];
description.RemoveAt(0);
returnValues.Add(
new CommandValue
{
DataType = { Name = first },
Description = description
}
);
continue;
}
returnValues.Add(
new CommandValue
{
DataType =
{
Name = see.Attribute("cref")?.Value?.Trim() ?? string.Empty,
Uri = see.Attribute("uri")?.Value?.Trim(),
Description = MamlGenerator.ToParagraphs(see.Value?.Trim())
},
Description = description
}
);
}
return(returnValues);
}
/// <summary>
/// Extract the examples for a Cmdlet parameter.
/// </summary>
/// <param name="cmdletType">
/// The CLR type that implements the Cmdlet.
/// </param>
/// <returns>
/// A list of example, which may be empty.
/// </returns>
public List <CommandExample> GetCmdletExamples(TypeInfo cmdletType)
{
if (cmdletType == null)
{
throw new ArgumentNullException(nameof(cmdletType));
}
var assemblyDoc = GetAssemblyDocumentation(cmdletType);
if (assemblyDoc == null)
{
return(null);
}
var rawExamples = assemblyDoc.GetExamples(cmdletType);
var examples = new List <CommandExample>();
foreach (var example in rawExamples)
{
var para = example.Elements("para");
var descriptions = para.Where(e => e.Attribute("type")?.Value == "description").Select(e => MamlGenerator.ToParagraphs(e.Value.Trim()));
var description = new List <string>();
foreach (var d in descriptions)
{
description.AddRange(d);
}
var remarks = para.Where(e => e.Attribute("type")?.Value != "description").Select(e => MamlGenerator.ToParagraphs(e.Value.Trim()));
var remark = new List <string>();
foreach (var r in remarks)
{
remark.AddRange(r);
}
examples.Add(
new CommandExample
{
Title = example.Element("title")?.Value.Trim() ?? "Example",
Description = description,
Code = string.Join("\n", example.Elements("code")?.InDocumentOrder().Select(e => e.Value)),
Remarks = remark
}
);
}
return(examples);
}