private void TryPortMissingSummaryForAPI(IDocsAPI dApiToUpdate, TripleSlashMember?tsMemberToPort, DocsMember?interfacedMember)
{
// Only port if undocumented in MS Docs
if (IsEmpty(dApiToUpdate.Summary))
{
bool isEII = false;
string name = string.Empty;
string value = string.Empty;
// Try to port triple slash comments
if (tsMemberToPort != null && !IsEmpty(tsMemberToPort.Summary))
{
dApiToUpdate.Summary = tsMemberToPort.Summary;
name = tsMemberToPort.Name;
value = tsMemberToPort.Summary;
}
// or try to find if it implements a documented interface
else if (interfacedMember != null && !IsEmpty(interfacedMember.Summary))
{
dApiToUpdate.Summary = interfacedMember.Summary;
isEII = true;
name = interfacedMember.MemberName;
value = interfacedMember.Summary;
}
if (!IsEmpty(value))
{
// Any member can have an empty summary
string message = $"{dApiToUpdate.Prefix} {GetIsEII(isEII)} SUMMARY";
PrintModifiedMember(message, dApiToUpdate.FilePath, dApiToUpdate.DocId);
TotalModifiedIndividualElements++;
}
}
}
private void TryPortMissingRemarksForAPI(IDocsAPI dApiToUpdate, IntelliSenseXmlMember?tsMemberToPort, DocsMember?interfacedMember, bool skipInterfaceRemarks)
{
if (dApiToUpdate.Kind == APIKind.Type && !Config.PortTypeRemarks ||
dApiToUpdate.Kind == APIKind.Member && !Config.PortMemberRemarks)
{
return;
}
if (dApiToUpdate.Remarks.IsDocsEmpty())
{
bool isEII = false;
string name = string.Empty;
string value = string.Empty;
// Try to port IntelliSense xml comments
if (tsMemberToPort != null && !tsMemberToPort.Remarks.IsDocsEmpty())
{
dApiToUpdate.Remarks = tsMemberToPort.Remarks;
name = tsMemberToPort.Name;
value = tsMemberToPort.Remarks;
}
// or try to find if it implements a documented interface
// which only happens in docs members (types have a null interfacedMember passed)
else if (interfacedMember != null && !interfacedMember.Remarks.IsDocsEmpty())
{
DocsMember memberToUpdate = (DocsMember)dApiToUpdate;
// Only attempt to port if the member name is the same as the interfaced member docid without prefix
if (memberToUpdate.MemberName == interfacedMember.DocId[2..])
{
string dMemberToUpdateTypeDocIdNoPrefix = memberToUpdate.ParentType.DocId[2..];
private bool TryGetEIIMember(IDocsAPI dApiToUpdate, out DocsMember?interfacedMember)
{
interfacedMember = null;
if (dApiToUpdate is DocsMember)
{
string interfacedMemberDocId = ((DocsMember)dApiToUpdate).ImplementsInterfaceMember;
if (!string.IsNullOrEmpty(interfacedMemberDocId))
{
interfacedMember = DocsComments.Members.FirstOrDefault(x => x.DocId == interfacedMemberDocId);
return(interfacedMember != null);
}
}
return(false);
}
private void TryPortMissingSummaryForAPI(IDocsAPI dApiToUpdate, IntelliSenseXmlMember?tsMemberToPort, DocsMember?interfacedMember)
{
if (dApiToUpdate.Kind == APIKind.Type && !Config.PortTypeSummaries ||
dApiToUpdate.Kind == APIKind.Member && !Config.PortMemberSummaries)
{
return;
}
// Only port if undocumented in MS Docs
if (dApiToUpdate.Summary.IsDocsEmpty())
{
bool isEII = false;
string name = string.Empty;
string value = string.Empty;
// Try to port IntelliSense xml comments
if (tsMemberToPort != null && !tsMemberToPort.Summary.IsDocsEmpty())
{
dApiToUpdate.Summary = tsMemberToPort.Summary;
name = tsMemberToPort.Name;
value = tsMemberToPort.Summary;
}
// or try to find if it implements a documented interface
else if (interfacedMember != null && !interfacedMember.Summary.IsDocsEmpty())
{
dApiToUpdate.Summary = interfacedMember.Summary;
isEII = true;
name = interfacedMember.MemberName;
value = interfacedMember.Summary;
}
if (!value.IsDocsEmpty())
{
// Any member can have an empty summary
string message = $"{dApiToUpdate.Kind} {GetIsEII(isEII)} summary: {name.Escaped()} = {value.Escaped()}";
PrintModifiedMember(message, dApiToUpdate.FilePath, dApiToUpdate.DocId);
TotalModifiedIndividualElements++;
}
}
}
private void TryPortMissingParamsForAPI(IDocsAPI dApiToUpdate, TripleSlashMember?tsMemberToPort, DocsMember?interfacedMember)
{
bool created;
bool isEII;
string name;
string value;
string prefix = dApiToUpdate.Prefix;
if (tsMemberToPort != null)
{
foreach (DocsParam dParam in dApiToUpdate.Params)
{
if (IsEmpty(dParam.Value))
{
created = false;
isEII = false;
name = string.Empty;
value = string.Empty;
TripleSlashParam tsParam = tsMemberToPort.Params.FirstOrDefault(x => x.Name == dParam.Name);
// When not found, it's a bug in Docs (param name not the same as source/ref), so need to ask the user to indicate correct name
if (tsParam == null)
{
ProblematicAPIs.AddIfNotExists($"Param=[{dParam.Name}] in Member DocId=[{dApiToUpdate.DocId}]");
if (tsMemberToPort.Params.Count() == 0)
{
ProblematicAPIs.AddIfNotExists($"Param=[{dParam.Name}] in Member DocId=[{dApiToUpdate.DocId}]");
Log.Warning($" There were no triple slash comments for param '{dParam.Name}' in {dApiToUpdate.DocId}");
}
else
{
created = TryPromptParam(dParam, tsMemberToPort, out TripleSlashParam? newTsParam);
if (newTsParam == null)
{
Log.Error($" There param '{dParam.Name}' was not found in triple slash for {dApiToUpdate.DocId}");
}
else
{
// Now attempt to document it
if (!IsEmpty(newTsParam.Value))
{
// try to port triple slash comments
dParam.Value = newTsParam.Value;
name = newTsParam.Name;
value = newTsParam.Value;
}
// or try to find if it implements a documented interface
else if (interfacedMember != null)
{
DocsParam interfacedParam = interfacedMember.Params.FirstOrDefault(x => x.Name == newTsParam.Name || x.Name == dParam.Name);
if (interfacedParam != null)
{
dParam.Value = interfacedParam.Value;
name = interfacedParam.Name;
value = interfacedParam.Value;
isEII = true;
}
}
}
}
}
// Attempt to port
else if (!IsEmpty(tsParam.Value))
{
// try to port triple slash comments
dParam.Value = tsParam.Value;
name = tsParam.Name;
value = tsParam.Value;
}
// or try to find if it implements a documented interface
else if (interfacedMember != null)
{
DocsParam interfacedParam = interfacedMember.Params.FirstOrDefault(x => x.Name == dParam.Name);
if (interfacedParam != null)
{
dParam.Value = interfacedParam.Value;
name = interfacedParam.Name;
value = interfacedParam.Value;
isEII = true;
}
}
if (!IsEmpty(value))
{
string message = $"{prefix} {GetIsEII(isEII)} PARAM '{dParam.Name}' ({GetIsCreated(created)})";
PrintModifiedMember(message, dApiToUpdate.FilePath, dApiToUpdate.DocId);
TotalModifiedIndividualElements++;
}
}
}
}
else if (interfacedMember != null)
{
foreach (DocsParam dParam in dApiToUpdate.Params)
{
if (IsEmpty(dParam.Value))
{
DocsParam interfacedParam = interfacedMember.Params.FirstOrDefault(x => x.Name == dParam.Name);
if (interfacedParam != null && !IsEmpty(interfacedParam.Value))
{
dParam.Value = interfacedParam.Value;
string message = $"{prefix} EII PARAM '{dParam.Name}' ({GetIsCreated(false)})";
PrintModifiedMember(message, dApiToUpdate.FilePath, dApiToUpdate.DocId);
TotalModifiedIndividualElements++;
}
}
}
}
}
private void TryPortMissingRemarksForAPI(IDocsAPI dApiToUpdate, TripleSlashMember?tsMemberToPort, DocsMember?interfacedMember)
{
if (Config.SkipRemarks)
{
return;
}
if (IsEmpty(dApiToUpdate.Remarks))
{
bool isEII = false;
string name = string.Empty;
string value = string.Empty;
// Try to port triple slash comments
if (tsMemberToPort != null && !IsEmpty(tsMemberToPort.Remarks))
{
dApiToUpdate.Remarks = tsMemberToPort.Remarks;
name = tsMemberToPort.Name;
value = tsMemberToPort.Remarks;
}
// or try to find if it implements a documented interface
else if (interfacedMember != null && !IsEmpty(interfacedMember.Remarks))
{
string eiiMessage = string.Empty;
DocsMember memberToUpdate = (DocsMember)dApiToUpdate;
// Special text for EIIs in Remarks
if (memberToUpdate.MemberName == interfacedMember.DocId.Substring(2))
{
string dMemberToUpdateTypeDocIdNoPrefix = memberToUpdate.ParentType.DocId.Substring(2);
string interfacedMemberTypeDocIdNoPrefix = interfacedMember.ParentType.DocId.Substring(2);
eiiMessage = $"This member is an explicit interface member implementation. It can be used only when the <xref:{dMemberToUpdateTypeDocIdNoPrefix}> instance is cast to an <xref:{interfacedMemberTypeDocIdNoPrefix}> interface.{Environment.NewLine + Environment.NewLine}";
}
string original = string.Empty;
if (!interfacedMember.Remarks.Contains(Configuration.ToBeAdded))
{
original = interfacedMember.Remarks
.CleanRemarksText("##Remarks")
.CleanRemarksText("## Remarks")
.CleanRemarksText("<![CDATA[")
.CleanRemarksText("]]>");
}
dApiToUpdate.Remarks = eiiMessage + original;
name = interfacedMember.MemberName;
value = interfacedMember.Remarks;
isEII = true;
}
if (!IsEmpty(value))
{
// Any member can have an empty remark
string message = $"{dApiToUpdate.Prefix} {GetIsEII(isEII)} REMARKS";
PrintModifiedMember(message, dApiToUpdate.FilePath, dApiToUpdate.DocId);
TotalModifiedIndividualElements++;
}
}
}
public DocsTypeParam(IDocsAPI parentAPI, XElement xeDocsTypeParam)
{
ParentAPI = parentAPI;
XEDocsTypeParam = xeDocsTypeParam;
}
public DocsException(IDocsAPI parentAPI, XElement xException)
{
ParentAPI = parentAPI;
XEException = xException;
OriginalValue = Value;
}
