/// <inheritdoc/>
public string ReplaceReferenceTag(TypeWithComment thisType, string text)
{
if (string.IsNullOrEmpty(text))
{
return("");
}
if (text.Contains("<see"))
{
text = Regex.Replace(text, @"<see cref=""(?<cref>([T|F|P|M|E]:[^\""]*))""\s*(/>|>(?<text>[^<]*)</see>)", m => ZString.Concat(" ", ResolveSeeElement(thisType, m), " "));
}
if (text.Contains("<seealso"))
{
text = Regex.Replace(text, @"<seealso cref=""(?<cref>([T|F|P|M|E]:[^\""]*))""\s*(/>|>(?<text>[^<]*)</seealso>)", m => ZString.Concat(" ", ResolveSeeElement(thisType, m), " "));
}
if (text.Contains("<paramref"))
{
text = Regex.Replace(text, @"<paramref name=""(?<name>([^\""]*))""\s*(/>|>(?<text>[^<]*)</paramref>)", m => ZString.Concat(" ", ResolveNameElement(thisType, m), " "));
}
if (text.Contains("<typeparamref"))
{
text = Regex.Replace(text, @"<typeparamref name=""(?<name>([^\""]*))""\s*(/>|>(?<text>[^<]*)</paramref>)", m => ZString.Concat(" ", ResolveNameElement(thisType, m), " "));
}
return(text);
}
/// <inheritdoc/>
public string FormatToLink(TypeWithComment thisType, EventInfoWithComment evt, string?displayFormat = null, string?anchorFormat = null)
{
string?fmt = anchorFormat ?? EventAnchorDefaultFormat;
TypeWithComment declaringType = evt.GetDeclaringTypeInfo();
if (object.Equals(thisType, declaringType) || evt.Info.DeclaringType.IsAssignableFrom(thisType.Info) || declaringType.Comment.IsEmpty)
{
string anchor = evt.Info.Name;
string displayText;
if (string.IsNullOrEmpty(displayFormat))
{
displayText = System.Web.HttpUtility.HtmlEncode(anchor);
}
else
{
displayText = ZString.Format(displayFormat, System.Web.HttpUtility.HtmlEncode(anchor));
}
if (string.IsNullOrEmpty(fmt))
{
return(ZString.Format("[{0}](#{1})", displayText, ToAnchor(anchor)));
}
else
{
return(ZString.Format("[{0}](#{1})", displayText, ToAnchor(ZString.Format(fmt, anchor))));
}
}
else
{
string anchor = ZString.Concat(declaringType.Info.FormatToReadableTypeName(false), ".", evt.Info.Name);
string displayText;
if (string.IsNullOrEmpty(displayFormat))
{
displayText = System.Web.HttpUtility.HtmlEncode(anchor);
}
else
{
displayText = ZString.Format(displayFormat, System.Web.HttpUtility.HtmlEncode(anchor));
}
string typeLink = ZString.Format("../{1}/{2}.md", FormatToReadableName(declaringType, false), declaringType.Namespace, declaringType.Name);
if (string.IsNullOrEmpty(fmt))
{
return(ZString.Format("[{0}]({1}#{2})", displayText, typeLink, ToAnchor(anchor)));
}
else
{
return(ZString.Format("[{0}]({1}#{2})", displayText, typeLink, ToAnchor(ZString.Format(fmt, anchor))));
}
}
}
/// <inheritdoc/>
public void WriteTypeDocument(TypeWithComment type, IClassDocumentFormatter formatter)
{
string filePath = GetTypeDocumentFilePath(type, false);
if (!TypeDocumentTemplateState.IsCompiled)
{
TypeDocumentTemplateState.Compile(typeof(TypeWithComment));
}
WriteDocument(type, filePath, Settings.TypeDodumentSettings?.Encoding, TypeDocumentTemplateState.Key, formatter);
}
/// <summary>
/// Outputs the information of the specified type to the document.
/// </summary>
/// <param name="type">The type information.</param>
/// <exception cref="NullReferenceException">
/// The document formatter is not set.
/// </exception>
public void WriteTypeDocument(TypeWithComment type)
{
var formatter = Settings.TypeDodumentSettings?.DocumentFormatter;
if (formatter == null)
{
throw new NullReferenceException("The document formatter is not set.");
}
WriteTypeDocument(type, formatter);
}
/// <summary>
/// Gets the document output file path for the specified type.
/// </summary>
/// <param name="type">The type information.</param>
/// <param name="relative">A value that indicates whether to return a relative path from the root directory.</param>
/// <returns></returns>
private string GetTypeDocumentFilePath(TypeWithComment type, bool relative)
{
string fileName = (Settings.TypeDodumentSettings?.FileNameFormatter ?? GetTypeDocumentFileName)(type);
if (relative)
{
return(Path.Combine(@"..\", $"{type.Namespace}", fileName));
}
else
{
return(Path.Combine(Settings.RootDirectory, $"{type.Namespace}", fileName));
}
}
/// <summary>
///
/// </summary>
/// <param name="thisType"></param>
/// <param name="match"></param>
/// <returns></returns>
private string ResolveNameElement(TypeWithComment thisType, Match match)
{
var name = match.Groups["name"]?.Value ?? "";
var text = match.Groups["text"]?.Value ?? "";
if (!string.IsNullOrWhiteSpace(text))
{
return(ZString.Format(ParameterNameDefaultFormat, text));
}
if (!string.IsNullOrWhiteSpace(name))
{
return(ZString.Format(ParameterNameDefaultFormat, name));
}
return("");
}
/// <inheritdoc />
public string FormatToLink(TypeWithComment type, bool isFullName, string?displayFormat = null, string?anchorFormat = null)
{
string displayText;
if (string.IsNullOrEmpty(displayFormat))
{
displayText = FormatToReadableName(type, isFullName);
}
else
{
displayText = ZString.Format(displayFormat, FormatToReadableName(type, isFullName));
}
if (type.Comment.IsEmpty)
{
return(displayText);
}
else
{
return(ZString.Format("[{0}](../{1}/{2}.md)", displayText, type.Namespace, type.Name));
}
}
/// <inheritdoc/>
public void WriteTypeDocument(TypeWithComment type, IClassDocumentFormatter formatter)
{
string filePath = GetTypeDocumentFilePath(type, false);
string dir = Path.GetDirectoryName(filePath);
if (!Directory.Exists(dir))
{
Directory.CreateDirectory(dir);
}
RazorEngine.Templating.DynamicViewBag viewBag = new RazorEngine.Templating.DynamicViewBag();
viewBag.AddValue("Formatter", formatter);
if (!TypeDocumentTemplateState.IsCompiled)
{
TypeDocumentTemplateState.Compile(typeof(TypeWithComment));
}
using (StreamWriter writer = new StreamWriter(filePath, false, Settings.TypeDodumentSettings.Encoding))
{
Engine.Run(TypeDocumentTemplateState.Key, writer, type.GetType(), type, viewBag: viewBag);
writer.Flush();
}
}
/// <inheritdoc />
public string FormatToAnchor(TypeWithComment type, string?format = null)
{
throw new NotImplementedException();
}
/// <inheritdoc />
public string FormatToReadableName(TypeWithComment type, bool isFullName)
{
return(System.Web.HttpUtility.HtmlEncode(type.Info.FormatToReadableTypeName(isFullName)));
}
/// <summary>
///
/// </summary>
/// <param name="thisType"></param>
/// <param name="match"></param>
/// <returns></returns>
private string ResolveSeeElement(TypeWithComment thisType, Match match)
{
var cref = match.Groups["cref"]?.Value ?? "";
var text = match.Groups["text"]?.Value ?? "";
if (!string.IsNullOrWhiteSpace(cref) && XmlCommentSignature.TryParse(cref, out var signature))
{
switch (signature.Kind)
{
case XmlCommentKind.Type:
if (Context.TryGetTypeInfo(signature, out var type))
{
return(FormatToLink(type, false, displayFormat: text));
}
else
{
return(signature.TypeName);
}
case XmlCommentKind.Method:
if (Context.TryGetMethodInfo(signature, out var method))
{
return(FormatToLink(thisType, method, displayFormat: text));
}
else
{
return(signature.MemberName ?? "");
}
case XmlCommentKind.Property:
if (Context.TryGetPropertyInfo(signature, out var prop))
{
return(FormatToLink(thisType, prop, displayFormat: text));
}
else
{
return(signature.MemberName ?? "");
}
case XmlCommentKind.Field:
if (Context.TryGetFieldInfo(signature, out var field))
{
return(FormatToLink(thisType, field, displayFormat: text));
}
else
{
return(signature.MemberName ?? "");
}
case XmlCommentKind.Event:
if (Context.TryGetEventInfo(signature, out var evt))
{
return(FormatToLink(thisType, evt, displayFormat: text));
}
else
{
return(signature.MemberName ?? "");
}
}
}
if (!string.IsNullOrWhiteSpace(text))
{
return(text);
}
if (!string.IsNullOrWhiteSpace(cref))
{
return(cref);
}
return("");
}
/// <summary>
/// Gets the document output file name for the specified type.
/// </summary>
/// <param name="type"></param>
/// <returns></returns>
private string GetTypeDocumentFileName(TypeWithComment type)
{
return($"{type.Name}.md");
}
/// <summary>
/// Outputs the information of the specified type to the document.
/// </summary>
/// <param name="type">The type information.</param>
public void WriteTypeDocument(TypeWithComment type)
{
WriteTypeDocument(type, Settings.TypeDodumentSettings?.DocumentFormatter);
}
