public async Task <ApiTocRenderingResult> RenderAsync(ApiReferenceId id,
ApiReferenceUri uri,
ApiReferenceTitle title,
ApiReferenceFlags flags,
ApiReferenceReturns returns,
ApiReferenceComment comment,
Dictionary <string, ApiReferenceEntity> entityCache,
string currentPath,
bool isAdvanced)
{
var state = new RenderingState(new StringBuilder(), id, uri, title, flags, returns, comment, entityCache, currentPath);
var cssClasses = new List <string> {
"table-of-contents-item"
};
if (isAdvanced)
{
cssClasses.Add("is-advanced");
}
state.AppendString($"<article class=\"{string.Join(" ", cssClasses)}\">");
WriteType(state);
WriteLink(state);
await WriteCommentAsync(state);
state.AppendString($"</article>");
return(new ApiTocRenderingResult(state.Builder.ToString(), state.DeferredMarkdownIds, state.NumberOfCommentLines));
}
public Task <ApiTocRenderingResult> RenderAsync(ApiReferenceId id,
ApiReferenceUri uri,
ApiReferenceTitle title,
ApiReferenceComment comment,
Dictionary <string, ApiReferenceEntity> entityCache,
string currentPath,
bool isAdvanced)
{
return(RenderAsync(id, uri, title, null, null, comment, entityCache, currentPath, isAdvanced));
}
public RenderingState(StringBuilder builder,
ApiReferenceId id,
ApiReferenceUri uri,
ApiReferenceTitle title,
ApiReferenceFlags flags,
ApiReferenceReturns returns,
ApiReferenceComment comment,
Dictionary <string, ApiReferenceEntity> entityCache,
string currentPath)
{
Builder = builder;
Id = id;
Uri = uri;
Title = title;
Flags = flags;
Returns = returns;
Comment = comment;
EntityCache = entityCache;
CurrentPath = currentPath;
}
private ApiReferenceComment.ApiReferenceCommentAttributeParameter FindParameterComment(string name, ApiReferenceComment comment)
{
return(comment?.Attributes?.Parameters?.FirstOrDefault(e => e.Name == name));
}
public static string GetTitle(ApiReferenceId id,
ApiReferenceTitle title,
ApiReferenceComment comment,
List <ApiReferenceParameter> parameters,
List <ApiReferenceAttribute> attributes,
Dictionary <string, ApiReferenceEntity> entityCache,
bool isIndex)
{
var attachedAttribute = GetAttachedAttributeInfo(id, title, parameters, attributes, entityCache);
if (!isIndex && attachedAttribute != null)
{
return($"{attachedAttribute.Name} attached {attachedAttribute.AttributeType} on {attachedAttribute.AttachedToType}");
}
// Try to capture the type name from the fully qualified title.
// This is basically stripping away any arguments, then taking the second last segment after
// splitting on period so that:
// > Fuse.Elements.Element.Equals(Fuse.Elements.Element other)
// turns into:
// > Element
string typeName = title.FullyQualifiedIndexTitle;
if (typeName.Contains("("))
{
typeName = typeName.Substring(0, typeName.IndexOf("("));
}
if (typeName.Contains("."))
{
var parts = typeName.Split('.');
typeName = parts[parts.Length - 2];
}
// JavaScript methods use the ScriptMethod comment property to determine title
if (id.Type == "JsMethod")
{
if (comment?.Attributes?.ScriptMethod == null)
{
throw new ArgumentException($"Found JsMethod without script method comment, unable to generate title: {id.Id}");
}
var name = comment.Attributes.ScriptMethod.Name + "(" + string.Join(", ", comment.Attributes.ScriptMethod.Parameters) + ")";
if (!isIndex)
{
name = typeName + "." + name + " Method (JS)";
}
return(name);
}
// JavaScript modules use ScriptModule comment property to determine title
if (id.Type == "JsModule")
{
if (string.IsNullOrWhiteSpace(comment?.Attributes?.ScriptModule))
{
throw new ArgumentException($"Found JsModule without script module comment, unable to generate title: {id.Id}");
}
var name = comment.Attributes.ScriptModule;
if (!isIndex)
{
name = name + " Module (JS)";
}
return(name);
}
// JavaScript properties use the ScriptProperty comment to determine title
if (id.Type == "JsProperty")
{
if (string.IsNullOrWhiteSpace(comment?.Attributes?.ScriptProperty))
{
throw new ArgumentException($"Found JsProperty without script property comment, unable to generate title: {id.Id}");
}
var name = comment.Attributes.ScriptProperty;
if (!isIndex)
{
name = typeName + "." + name + " Property (JS)";
}
return(name);
}
// JavaScript events uses the ScriptEvent comment to determine title
if (id.Type == "JsEvent")
{
if (string.IsNullOrWhiteSpace(comment?.Attributes?.ScriptEvent))
{
throw new ArgumentException($"Found JsEvent without script event comment, unable to generate title: {id.Id}");
}
var name = comment.Attributes.ScriptEvent;
if (!isIndex)
{
name = typeName + "." + name + " Event (JS)";
}
return(name);
}
// Constructors should be named "<type> Constructor" in index titles for clarity
if (id.Type == "Constructor" && isIndex)
{
return(title.IndexTitle + " Constructor");
}
// Attached attributes should have their prefix removed so it only lists the name of the actual attribute
if (isIndex && id.Type.StartsWith("AttachedUx") && title.IndexTitle.Contains("."))
{
return(title.IndexTitle.Split('.')[1]);
}
// Fall back to the title defined on the object
return(isIndex ? title.IndexTitle : title.PageTitle);
}
