protected override MdBlock ConvertToBlock()
{
var detailSections = Enumerable.Empty <ParameterDetailsSection>()
.Concat(m_Model.PositionalParameters.Select(v => new PositionalParameterDetailsSection(v)).Cast <ParameterDetailsSection>())
.Concat(m_Model.NamedParameters.Select(o => new NamedParameterDetailsSection(o)).Cast <ParameterDetailsSection>())
.Concat(m_Model.SwitchParameters.Select(o => new SwitchParameterDetailsSection(o)).Cast <ParameterDetailsSection>())
.ToArray();
var anchors = detailSections.ToDictionary(x => x.Parameter, x => x.Heading.Anchor);
var block = new MdContainerBlock()
{
new MdHeading(2, "Parameters"),
new CommandParametersTable(m_Model, parameter => anchors[parameter], parameter => anchors[parameter], parameter => anchors[parameter])
};
var first = true;
foreach (var section in detailSections)
{
if (detailSections.Length > 1 && !first)
{
block.Add(new MdThematicBreak());
}
block.Add(section);
first = false;
}
return(block);
}
public void Visit(MdContainerBlock containerBlock)
{
foreach (var block in containerBlock)
{
block.Accept(this);
}
}
protected virtual void AddParametersSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (overload.Parameters.Count == 0)
{
return;
}
var parametersBlock = new MdContainerBlock();
block.Add(parametersBlock);
parametersBlock.Add(new MdHeading("Parameters", headingLevel));
foreach (var parameter in overload.Parameters)
{
parametersBlock.Add(
new MdParagraph(
new MdCodeSpan(parameter.Name),
" ",
GetMdSpan(parameter.ParameterType)
));
if (parameter.Description != null)
{
parametersBlock.Add(ConvertToBlock(parameter.Description));
}
}
}
public void ConvertToBlock_returns_expected_result_for_for_lists([CombinatorialValues(ListType.Bullet, ListType.None, ListType.Number)] ListType listType)
{
// ARRANGE
var input = CreateList(
listType,
null,
CreateListItem("Description 1"),
CreateListItem("Term 2", "Description 2")
);
var list = listType == ListType.Number ? new MdOrderedList() : (MdList) new MdBulletList();
list.Add(
new MdListItem(
new MdParagraph("Description 1")));
list.Add(
new MdListItem(
new MdParagraph(new MdStrongEmphasisSpan("Term 2", ":"), " "),
new MdParagraph("Description 2")));
var expected = new MdContainerBlock(list);
// ACT
var actual = TextBlockToMarkdownConverter.ConvertToBlock(input, Mock.Of <IMdSpanFactory>());
// ASSERT
AssertEquals(expected, actual);
}
private void AddRemarksSection(MdContainerBlock block)
{
if (!Model.Remarks.IsEmpty)
{
block.Add(new MdHeading(2, "Remarks"));
block.Add(ConvertToBlock(Model.Remarks));
}
}
protected virtual void AddDefinitionSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (!overload.Summary.IsEmpty)
{
block.Add(ConvertToBlock(overload.Summary));
}
block.Add(new MdCodeBlock(overload.CSharpDefinition, "csharp"));
}
public ConvertToBlockVisitor(IMdSpanFactory spanFactory)
{
m_SpanFactory = spanFactory ?? throw new ArgumentNullException(nameof(spanFactory));
Result = new MdContainerBlock();
m_Blocks = new Stack <MdContainerBlockBase>();
m_Blocks.Push(Result);
}
protected override void AddValueSection(MdContainerBlock block)
{
block.Add(new MdHeading("Field Value", 2));
block.Add(GetMdParagraph(Model.Type));
if (!Model.Value.IsEmpty)
{
block.Add(ConvertToBlock(Model.Value));
}
}
private void AddExampleSection(MdContainerBlock block)
{
if (Model.Example.IsEmpty)
{
return;
}
block.Add(new MdHeading("Example", 2));
block.Add(ConvertToBlock(Model.Example));
}
protected virtual void AddRemarksSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (overload.Remarks.IsEmpty)
{
return;
}
block.Add(new MdHeading("Remarks", headingLevel));
block.Add(ConvertToBlock(overload.Remarks));
}
protected virtual void AddExampleSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (overload.Example.IsEmpty)
{
return;
}
block.Add(new MdHeading("Example", headingLevel));
block.Add(ConvertToBlock(overload.Example));
}
protected virtual void AddExampleSection(MdContainerBlock block)
{
if (Model.Example.IsEmpty)
{
return;
}
block.Add(new MdHeading(2, "Example"));
block.Add(ConvertToBlock(Model.Example));
}
protected virtual void AddRemarksSection(MdContainerBlock block)
{
if (Model.Remarks.IsEmpty)
{
return;
}
block.Add(new MdHeading(2, "Remarks"));
block.Add(ConvertToBlock(Model.Remarks));
}
private void AddSeeAlsoSection(MdContainerBlock block)
{
if (Model.SeeAlso.Count > 0)
{
block.Add(new MdHeading(2, "See Also"));
block.Add(
new MdBulletList(
Model.SeeAlso.Select(seeAlso => new MdListItem(ConvertToSpan(seeAlso)))
));
}
}
protected virtual void AddDefinitionSection(MdContainerBlock block)
{
if (!Model.Summary.IsEmpty)
{
block.Add(ConvertToBlock(Model.Summary));
}
block.Add(
new MdCodeBlock(Model.CSharpDefinition, "csharp")
);
}
private void AddValueSubSection(MdContainerBlock block, IndexerOverloadDocumentation overload, int headingLevel)
{
block.Add(new MdHeading("Indexer Value", headingLevel));
block.Add(
GetMdParagraph(overload.Type)
);
if (overload.Value != null)
{
block.Add(ConvertToBlock(overload.Value));
}
}
public void ConvertToBlock_returns_expected_result_for_a_TextBlock()
{
// ARRANGE
var input = CreateTextBlock(new TextElement("My Text"));
var expected = new MdContainerBlock(new MdParagraph("My Text"));
// ACT
var actual = TextBlockToMarkdownConverter.ConvertToBlock(input, Mock.Of <IMdSpanFactory>());
// ASSERT
AssertEquals(expected, actual);
}
protected virtual void AddSeeAlsoSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (overload.SeeAlso.Count == 0)
{
return;
}
block.Add(new MdHeading("See Also", headingLevel));
block.Add(
new MdBulletList(
overload.SeeAlso.Select(seeAlso => new MdListItem(ConvertToSpan(seeAlso)))
));
}
public void DeepEquals_returns_expected_value()
{
var instance1 = new MdContainerBlock(new MdParagraph());
var instance2 = new MdContainerBlock(new MdParagraph());
var instance3 = new MdContainerBlock(new MdParagraph(new MdTextSpan("Text")));
Assert.True(instance1.DeepEquals(instance1));
Assert.True(instance1.DeepEquals(instance2));
Assert.False(instance1.DeepEquals(null));
Assert.False(instance1.DeepEquals(instance3));
Assert.False(instance1.DeepEquals(new MdParagraph()));
}
protected override void AddValueSection(MdContainerBlock block)
{
block.Add(new MdHeading("Property Value", 2));
block.Add(
GetMdParagraph(Model.Type)
);
if (Model.Value != null)
{
block.Add(ConvertToBlock(Model.Value));
}
// After the value section, add the Exceptions section
AddExceptionsSection(block);
}
private void AddNamespacesList(MdContainerBlock block)
{
if (!Model.Namespaces.Any())
{
return;
}
block.Add(new MdHeading(2, "Namespaces"));
block.Add(
new MdBulletList(
Model.Namespaces
.OrderBy(x => x.Name, StringComparer.Ordinal)
.Select(@namespace => new MdListItem(GetMdSpan(@namespace.NamespaceId))
)));
}
private void AddExceptionsSection(MdContainerBlock block)
{
if (Model.Exceptions.Count == 0)
{
return;
}
block.Add(new MdHeading("Exceptions", 2));
foreach (var exception in Model.Exceptions)
{
block.Add(
GetMdParagraph(exception.Type),
ConvertToBlock(exception.Text)
);
}
}
protected virtual void AddExceptionsSubSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
if (overload.Exceptions.Count == 0)
{
return;
}
block.Add(new MdHeading("Exceptions", headingLevel));
foreach (var exception in overload.Exceptions)
{
block.Add(
GetMdParagraph(exception.Type),
ConvertToBlock(exception.Text)
);
}
}
private void AddSimpleMembersSection(MdContainerBlock block, string sectionHeading, IEnumerable <SimpleMemberDocumentation> members)
{
if (members.Any())
{
block.Add(new MdHeading(sectionHeading, 2));
var table = new MdTable(new MdTableRow("Name", "Description"));
foreach (var member in members.OrderBy(x => x.Name, StringComparer.Ordinal))
{
table.Add(
new MdTableRow(
CreateLink(member.MemberId, member.Name),
ConvertToSpan(member.Summary)
));
}
block.Add(table);
}
}
protected void AddOverloadsTableSection(MdContainerBlock block, IEnumerable <TOverload> overloads, int headingLevel)
{
var table = new MdTable(new MdTableRow("Signature", "Description"));
foreach (var overload in overloads)
{
// optimization: we know the section we're linking to is on the same page
// so we can create the link to the anchor without going through PageBase.CreateLink()
var link = new MdLinkSpan(overload.Signature, "#" + m_Headings.Value[overload.MemberId].Anchor);
table.Add(
new MdTableRow(link, ConvertToSpan(overload.Summary))
);
}
block.Add(
new MdHeading("Overloads", headingLevel),
table
);
}
public void Initialization_of_MdContainerBlock_using_constructor()
{
_ = new MdContainerBlock();
_ = new MdContainerBlock(new MdContainerBlock());
_ = new MdContainerBlock(new MdContainerBlock(), new MdContainerBlock());
_ = new MdContainerBlock(new MdListItem());
_ = new MdContainerBlock(new MdListItem(), new MdListItem());
_ = new MdContainerBlock(new MdBlockQuote());
_ = new MdContainerBlock(new MdBlockQuote(), new MdBlockQuote());
_ = new MdContainerBlock(new MdBulletList());
_ = new MdContainerBlock(new MdOrderedList());
_ = new MdContainerBlock(new MdAdmonition("note"));
_ = new MdContainerBlock(new MdAdmonition("note"), new MdAdmonition("note"));
}
public void ConvertToBlock_returns_expected_result_for_lists_02([CombinatorialValues(1, 2, 10)] int numberOfListItems)
{
// ARRANGE
var input = CreateList(
ListType.Number,
null,
Enumerable.Range(1, numberOfListItems).Select(i => CreateListItem($"Item {i}"))
);
var expected = new MdContainerBlock(
new MdOrderedList(
Enumerable.Range(1, numberOfListItems).Select(i => new MdListItem($"Item {i}"))
));
// ACT
var actual = TextBlockToMarkdownConverter.ConvertToBlock(input, Mock.Of <IMdSpanFactory>());
// ASSERT
AssertEquals(expected, actual);
}
protected void AddDeclaringTypeSection(MdContainerBlock block)
{
var paragraph = new MdParagraph(
new MdStrongEmphasisSpan("Declaring Type:"), " ", GetMdSpan(Model.TypeDocumentation.TypeId),
"\r\n",
new MdStrongEmphasisSpan("Namespace:"), " ", GetMdSpan(Model.TypeDocumentation.NamespaceDocumentation.NamespaceId),
"\r\n",
new MdStrongEmphasisSpan("Assembly:"), " " + Model.AssemblyDocumentation.Name
);
if (m_Configuration.Template.Default.IncludeVersion)
{
paragraph.Add("\r\n");
paragraph.Add(new MdCompositeSpan(
new MdStrongEmphasisSpan("Assembly Version:"), " " + Model.AssemblyDocumentation.Version)
);
}
block.Add(paragraph);
}
protected virtual void AddOverloadSection(MdContainerBlock block, TOverload overload, int headingLevel)
{
AddObsoleteWarning(block, overload);
AddDefinitionSubSection(block, overload, headingLevel + 1);
AddTypeParametersSubSection(block, overload, headingLevel + 1);
AddParametersSubSection(block, overload, headingLevel + 1);
AddRemarksSubSection(block, overload, headingLevel + 1);
AddReturnsSubSection(block, overload, headingLevel + 1);
AddExceptionsSubSection(block, overload, headingLevel + 1);
AddExampleSubSection(block, overload, headingLevel + 1);
AddSeeAlsoSubSection(block, overload, headingLevel + 1);
}
/// <summary>
/// Gets the change log's content block
/// </summary>
protected virtual MdBlock GetChangeLogContentBlock(ApplicationChangeLog model)
{
var container = new MdContainerBlock();
// for each version, add the changes to the document
// (changeLog.ChangeLogs is ordered by version)
var firstElement = true;
foreach (var versionChangeLog in model.ChangeLogs)
{
if (!firstElement)
{
container.Add(new MdThematicBreak());
}
container.Add(GetVersionBlock(versionChangeLog));
firstElement = false;
}
return(container);
}
