private void WriteTypesOverviewTable(IAssemblyReflector assembly, SlashdocSummaryHtmlFormatter formatter)
{
WriteDescriptionTableHeader("Types");
foreach (var type in assembly.Types
.Where(t => ReflectionHelper.IsVisible(t))
.OrderBy(t => _language.GetDisplayName(t)))
{
var displayName = _language.GetDisplayName(type);
_writer.WriteStartElement("tr");
_writer.WriteStartElement("td");
_writer.WriteStartElement("a");
_writer.WriteAttributeString("href", "#" + displayName);
_writer.WriteString(displayName);
_writer.WriteEndElement(); // a
_writer.WriteString(" " + _language.GetMetaTypeName(type));
_writer.WriteEndElement(); // td
_writer.WriteStartElement("td");
var slashdocSummaryHtml = formatter.FormatSummary(LookupXmlDescription(
SlashdocIdentifierProvider.GetId(type),
displayName + " " + _language.GetMetaTypeName(type)));
_writer.WriteRaw(slashdocSummaryHtml);
_writer.WriteEndElement(); // td
_writer.WriteEndElement(); // tr
}
WriteDescriptionTableFooter();
}
public void ShouldIncludeParameterNamesAsText()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary("<summary>Hello, <paramref name=\"World\" />!</summary>"), Is.EqualTo("Hello, World!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <typeparamref name=\"World\" />!</summary>"), Is.EqualTo("Hello, World!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <paramref />!</summary>"), Is.EqualTo("Hello, !"), "The parser doesn't choke when the attribute is missing.");
}
public void ShouldOnlyIncludeContentWithinSummaryTags()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary("<far-out>dude</far-out>"), Is.EqualTo(string.Empty));
Assert.That(formatter.FormatSummary("<far-out><summary>dude</summary></far-out>"), Is.EqualTo("dude"));
Assert.That(formatter.FormatSummary("<summary>first</summary><summary><summary>second<summary/></summary></summary>"), Is.EqualTo("firstsecond"));
Assert.That(formatter.FormatSummary("irrelevant <summary/> irrelevant"), Is.EqualTo(string.Empty));
}
public void DescribeType(Type type, SlashdocSummaryHtmlFormatter formatter)
{
if (type == null)
{
throw new ArgumentNullException("type");
}
_writer.WriteStartElement("div");
_writer.WriteAttributeString("id", _language.GetDisplayName(type));
var displayName = _language.GetShortDisplayName(type);
var metaType = _language.GetMetaTypeName(type);
WriteTypeHeader(type, displayName, metaType, formatter);
if (type.IsEnum)
{
var values = ReflectionHelper.GetEnumMembers(type)
.OrderBy(x => x.GetRawConstantValue());
WriteSection("Members", values, (x) => x.Name, (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
}
else if (!HideMembers(type))
{
WriteTextElement("p", string.Format(CultureInfo.InvariantCulture, "The {0} {1} exposes the following members.", displayName, metaType));
var constructors = ReflectionHelper.GetVisibleConstructors(type)
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Constructors", constructors, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
var properties = ReflectionHelper.GetVisibleProperties(type)
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Properties", properties, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
var methods = ReflectionHelper.GetVisibleMethods(type)
.Where(x => !ReflectionHelper.IsTrivialMethod(x))
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Methods", methods, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
var operators = ReflectionHelper.GetVisibleOperators(type)
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Operators", operators, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
var fields = ReflectionHelper.GetVisibleFields(type)
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Fields", fields, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
var events = ReflectionHelper.GetVisibleEvents(type)
.OrderBy(x => SlashdocIdentifierProvider.GetId(x));
WriteSection("Events", events, (x) => _language.GetSignature(x), (x) => SlashdocIdentifierProvider.GetId(x), (x) => displayName + "." + x.Name, formatter);
}
_writer.WriteEndElement(); // div
}
public void DescribeAssembly(IAssemblyReflector assembly)
{
var formatter = new SlashdocSummaryHtmlFormatter(assembly, _language);
var title = string.Format(CultureInfo.InvariantCulture, "{0} public API reference", assembly.SimpleName);
WriteTextElement("h1", title);
WriteTypesOverviewTable(assembly, formatter);
foreach (var type in assembly.Types
.Where(t => ReflectionHelper.IsVisible(t))
.OrderBy(t => _language.GetShortDisplayName(t)))
{
DescribeType(type, formatter);
}
}
public void ShouldCreateFragmentLinksForTypeReferencesWithinTheSameAssembly()
{
var assemblyReflectorMock = new Mock<IAssemblyReflector>();
assemblyReflectorMock.Setup(x => x.LookupType("System.Guid")).Returns(typeof(System.Guid));
var formatter = new SlashdocSummaryHtmlFormatter(assemblyReflectorMock.Object, new CSharpSignatureProvider());
// T:System.Guid: type lookup is successful
Assert.That(formatter.FormatSummary("<summary>Hello, <see cref=\"T:System.Guid\" />!</summary>"), Is.EqualTo("Hello, <a href=\"#System.Guid\">Guid</a>!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <seealso cref=\"T:System.Guid\" />!</summary>"), Is.EqualTo("Hello, <a href=\"#System.Guid\">Guid</a>!"));
// T:System.EventArgs: type lookup fails
Assert.That(formatter.FormatSummary("<summary>Hello, <see cref=\"T:System.EventArgs\" />!</summary>"), Is.EqualTo("Hello, System.EventArgs!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <seealso cref=\"T:System.EventArgs\" />!</summary>"), Is.EqualTo("Hello, System.EventArgs!"));
// !:Error, E:Foo.Bar: no type lookup, just strip the meta-type identifier
Assert.That(formatter.FormatSummary("<summary>Hello, <see cref=\"!:Error\" />!</summary>"), Is.EqualTo("Hello, Error!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <seealso cref=\"!:Error\" />!</summary>"), Is.EqualTo("Hello, Error!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <see cref=\"E:Foo.Bar\" />!</summary>"), Is.EqualTo("Hello, Foo.Bar!"));
Assert.That(formatter.FormatSummary("<summary>Hello, <see />!</summary>"), Is.EqualTo("Hello, !"), "The parser doesn't choke when the attribute is missing.");
}
private void WriteTypeHeader(Type type, string displayName, string metaType, SlashdocSummaryHtmlFormatter formatter)
{
WriteTextElement("h2", string.Format(CultureInfo.InvariantCulture, "{0} {1}", displayName, metaType));
_writer.WriteStartElement("table");
_writer.WriteAttributeString("class", "typeheader");
_writer.WriteStartElement("tr");
_writer.WriteStartElement("td");
var slashdocSummaryHtml = formatter.FormatSummary(LookupXmlDescription(
SlashdocIdentifierProvider.GetId(type),
_language.GetDisplayName(type) + " " + _language.GetMetaTypeName(type)));
_writer.WriteRaw(slashdocSummaryHtml);
WriteInfo("Namespace", type.Namespace);
WriteInfo("Signature", _language.GetSignature(type));
_writer.WriteEndElement(); // td
_writer.WriteEndElement(); // tr
_writer.WriteEndElement(); // table
}
private void WriteSection <T>(string sectionHeading, IEnumerable <T> items, Func <T, string> signatureProvider, Func <T, string> slashdocIdProvider, Func <T, string> contextProvider, SlashdocSummaryHtmlFormatter formatter)
{
if (items.Count() > 0)
{
WriteDescriptionTableHeader(sectionHeading);
foreach (var item in items)
{
_writer.WriteStartElement("tr");
WriteTextElement("td", signatureProvider(item));
_writer.WriteStartElement("td");
var slashdocSummaryHtml = formatter.FormatSummary(LookupXmlDescription(
slashdocIdProvider(item),
contextProvider(item)));
_writer.WriteRaw(slashdocSummaryHtml);
_writer.WriteEndElement(); // td
_writer.WriteEndElement(); // tr
}
WriteDescriptionTableFooter();
}
}
public void ShouldReturnAnEmptySummaryWhenTheXmlDescriptionIsNullOrEmpty()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary(null), Is.EqualTo(string.Empty));
Assert.That(formatter.FormatSummary(string.Empty), Is.EqualTo(string.Empty));
}
public void ShouldMarkupParagraphs()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary("<summary><para>Hello</para>!</summary>"), Is.EqualTo("<p>Hello</p>!"));
}
public void ShouldMarkupCode()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary("<summary><c>Hello</c>!</summary>"), Is.EqualTo("<code>Hello</code>!"));
Assert.That(formatter.FormatSummary("<summary><code>Hello</code>!</summary>"), Is.EqualTo("<code>Hello</code>!"));
}
public void ShouldEscapeXmlDocumentEscapeCharacters()
{
var formatter = new SlashdocSummaryHtmlFormatter(DummyAssembly, DummyLanguage);
Assert.That(formatter.FormatSummary("<summary><hello> & goodbye</summary>"), Is.EqualTo("<hello> & goodbye"));
}