Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix inheritdoc bugs for full or partial inheritance #130

Merged
merged 2 commits into from
Sep 9, 2022
Merged

Fix inheritdoc bugs for full or partial inheritance #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9566fe0
Fix inheritdoc bugs for full or partial inheritance:
carlossanlop Sep 9, 2022
625aaf6
Merge branch 'dotnet:main' into FixInheritDocBugs
carlossanlop Sep 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions src/PortToDocs/src/libraries/Docs/DocsAPI.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ internal abstract class DocsAPI : IDocsAPI
public abstract bool Changed { get; set; }
public string FilePath { get; set; } = string.Empty;

public string DocId => _docId ??= GetApiSignatureDocId().AsEscapedDocId();
public string DocId => _docId ??= GetApiSignatureDocId();

public string DocIdUnprefixed => _docIdUnprefixed ??= DocId[2..];

Expand Down Expand Up @@ -148,7 +148,7 @@ public List<string> SeeAlsoCrefs
{
if (Docs != null)
{
_seeAlsoCrefs = Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref").AsEscapedDocId()).ToList();
_seeAlsoCrefs = Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref")).ToList();
}
else
{
Expand All @@ -167,7 +167,7 @@ public List<string> AltMembers
{
if (Docs != null)
{
_altMemberCrefs = Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref").AsEscapedDocId()).ToList();
_altMemberCrefs = Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref")).ToList();
}
else
{
Expand Down Expand Up @@ -221,7 +221,7 @@ public string InheritDocCref
XAttribute? xInheritDocCref = XInheritDoc.Attribute("cref");
if (xInheritDocCref != null)
{
_inheritDocCref = xInheritDocCref.Value.AsEscapedDocId();
_inheritDocCref = xInheritDocCref.Value;
}
}
}
Expand All @@ -238,7 +238,7 @@ public string InheritDocCref
// Non-null to add
else
{
_inheritDocCref = value.AsEscapedDocId(); // Can be empty string too
_inheritDocCref = value; // Can be empty string too
if (XInheritDoc == null) // Not found in Docs
{
XInheritDoc = new XElement("inheritdoc");
Expand Down
2 changes: 1 addition & 1 deletion src/PortToDocs/src/libraries/Docs/DocsException.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ public IDocsAPI ParentAPI
get; private set;
}

public string Cref => XmlHelper.GetAttributeValue(XEException, "cref").AsEscapedDocId();
public string Cref => XmlHelper.GetAttributeValue(XEException, "cref");

public string Value
{
Expand Down
4 changes: 2 additions & 2 deletions src/PortToDocs/src/libraries/IntelliSenseXml/IntelliSenseXmlMember.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ public string InheritDocCref
XAttribute? xInheritDocCref = XInheritDoc.Attribute("cref");
if (xInheritDocCref != null)
{
_inheritDocCref = xInheritDocCref.Value.AsEscapedDocId();
_inheritDocCref = xInheritDocCref.Value;
}
}
}
Expand Down Expand Up @@ -66,7 +66,7 @@ public string Namespace
/// <summary>
/// The API DocId.
/// </summary>
public string Name => _name ??= XmlHelper.GetAttributeValue(XEMember, "name").AsEscapedDocId();
public string Name => _name ??= XmlHelper.GetAttributeValue(XEMember, "name");

private List<IntelliSenseXmlParam>? _params;
public List<IntelliSenseXmlParam> Params
Expand Down
120 changes: 109 additions & 11 deletions src/PortToDocs/src/libraries/ToDocsPorter.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@

using System;
using System.Collections.Generic;
using System.Diagnostics.SymbolStore;
using System.IO;
using System.Linq;
using System.Text;
Expand Down Expand Up @@ -212,6 +213,18 @@ private void PortMissingCommentsForType(DocsType dTypeToUpdate)
Remarks = tsActualTypeToPort.Remarks
};

// delegates
foreach (IntelliSenseXmlParam tsParam in tsTypeToPort.Params)
{
mc.Params.Add(tsParam.Name, tsParam.Value);
}

// type typeparams
foreach (IntelliSenseXmlTypeParam tsTypeParam in tsTypeToPort.TypeParams)
{
mc.TypeParams.Add(tsTypeParam.Name, tsTypeParam.Value);
}

// Rare case where the base type or interface docs should be used
if (tsTypeToPort.InheritDoc)
{
Expand Down Expand Up @@ -258,6 +271,16 @@ private void PortMissingCommentsForMember(DocsMember dMemberToUpdate)
mc.Property = GetPropertyValue(tsMemberToPort.Value, tsMemberToPort.Returns);
}

foreach (IntelliSenseXmlParam tsParam in tsMemberToPort.Params)
{
mc.Params.Add(tsParam.Name, tsParam.Value);
}

foreach (IntelliSenseXmlTypeParam tsTypeParam in tsMemberToPort.TypeParams)
{
mc.TypeParams.Add(tsTypeParam.Name, tsTypeParam.Value);
}

// Rare case where the base type or interface docs should be used,
// but only for elements that aren't explicitly documented in the actual API
if (tsMemberToPort.InheritDoc)
Expand Down Expand Up @@ -313,7 +336,18 @@ private void GetMissingCommentsForTypeFromInheritDoc(MissingComments mc, DocsTyp
mc.Summary = tsInheritedMember.Summary;
mc.Returns = tsInheritedMember.Returns;
mc.Remarks = tsInheritedMember.Remarks;


// delegates
foreach (IntelliSenseXmlParam tsParam in tsInheritedMember.Params)
{
mc.Params.Add(tsParam.Name, tsParam.Value);
}

// type typeparams
foreach (IntelliSenseXmlTypeParam tsTypeParam in tsInheritedMember.TypeParams)
{
mc.TypeParams.Add(tsTypeParam.Name, tsTypeParam.Value);
}
}
// Look for the base type from which this one inherits
else if (DocsComments.Types.TryGetValue($"T:{dTypeToUpdate.BaseTypeName}", out DocsType? dBaseType) &&
Expand All @@ -329,6 +363,18 @@ private void GetMissingCommentsForTypeFromInheritDoc(MissingComments mc, DocsTyp
mc.Summary = dBaseType.Summary;
mc.Returns = dBaseType.Returns;
mc.Remarks = dBaseType.Remarks;

// delegates
foreach (DocsParam tsParam in dBaseType.Params)
{
mc.Params.Add(tsParam.Name, tsParam.Value);
}

// type typeparams
foreach (DocsTypeParam tsTypeParam in dBaseType.TypeParams)
{
mc.TypeParams.Add(tsTypeParam.Name, tsTypeParam.Value);
}
}
}

Expand Down Expand Up @@ -358,6 +404,22 @@ private void GetMissingCommentsForMemberFromInheritDoc(MissingComments mc, DocsM
{
mc.Property = GetPropertyValue(tsInheritedMember.Value, tsInheritedMember.Returns);
}

foreach (IntelliSenseXmlParam tsParam in tsInheritedMember.Params)
{
if (!mc.Params.TryAdd(tsParam.Name, tsParam.Value))
{
mc.Params[tsParam.Name] = tsParam.Value;
}
}

foreach (IntelliSenseXmlTypeParam tsTypeParam in tsInheritedMember.TypeParams)
{
if (!mc.TypeParams.TryAdd(tsTypeParam.Name, tsTypeParam.Value))
{
mc.TypeParams[tsTypeParam.Name] = tsTypeParam.Value;
}
}
}
// Look for the base type and find the member from which this one inherits
else if (DocsComments.Types.TryGetValue($"T:{dMemberToUpdate.ParentType.BaseTypeName}", out DocsType? dBaseType) &&
Expand Down Expand Up @@ -397,6 +459,22 @@ private void GetMissingCommentsForMemberFromInheritDoc(MissingComments mc, DocsM
{
mc.Property = GetPropertyValue(dBaseMember.Value, dBaseMember.Returns);
}

foreach (DocsParam baseParam in dBaseMember.Params)
{
if (!mc.Params.TryAdd(baseParam.Name, baseParam.Value))
{
mc.Params[baseParam.Name] = baseParam.Value;
}
}

foreach (DocsTypeParam baseTypeParam in dBaseMember.TypeParams)
{
if (!mc.TypeParams.TryAdd(baseTypeParam.Name, baseTypeParam.Value))
{
mc.TypeParams[baseTypeParam.Name] = baseTypeParam.Value;
}
}
}
}
}
Expand All @@ -413,13 +491,29 @@ private MissingComments GetMissingCommentsForMemberFromInterface(MissingComments
mc.Property = GetPropertyValue(dInterfacedMember.Value, dInterfacedMember.Returns);
}

foreach (DocsParam interfaceParam in dInterfacedMember.Params)
{
if (!mc.Params.TryAdd(interfaceParam.Name, interfaceParam.Value))
{
mc.Params[interfaceParam.Name] = interfaceParam.Value;
}
}

foreach (DocsTypeParam interfaceTypeParam in dInterfacedMember.TypeParams)
{
if (!mc.TypeParams.TryAdd(interfaceTypeParam.Name, interfaceTypeParam.Value))
{
mc.TypeParams[interfaceTypeParam.Name] = interfaceTypeParam.Value;
}
}

if (!dInterfacedMember.Remarks.IsDocsEmpty())
{
// Only attempt to port if the member name is the same as the interfaced member docid without prefix
if (dMemberToUpdate.MemberName == dInterfacedMember.DocId[2..])
if (dMemberToUpdate.MemberName == dInterfacedMember.DocIdUnprefixed)
{
string dMemberToUpdateTypeDocIdNoPrefix = dMemberToUpdate.ParentType.DocId[2..];
string interfacedMemberTypeDocIdNoPrefix = dInterfacedMember.ParentType.DocId[2..];
string dMemberToUpdateTypeDocIdNoPrefix = dMemberToUpdate.ParentType.DocIdUnprefixed;
string interfacedMemberTypeDocIdNoPrefix = dInterfacedMember.ParentType.DocIdUnprefixed;

// Special text for EIIs in Remarks
string 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.";
Expand Down Expand Up @@ -840,7 +934,7 @@ private void TryPortMissingExceptionsForMember(DocsMember dMemberToUpdate, Intel
// First time adding the cref
if (dException == null && Config.PortExceptionsNew)
{
AddedExceptions.Add($"Exception=[{tsException.Cref}] in Member=[{dMemberToUpdate.DocId}]");
AddedExceptions.Add($"Exception=[{tsException.Cref.AsEscapedDocId()}] in Member=[{dMemberToUpdate.DocId}]");
string text = XmlHelper.ReplaceExceptionPatterns(XmlHelper.GetNodesInPlainText(tsException.XEException));
dException = dMemberToUpdate.AddException(tsException.Cref, text);
created = true;
Expand All @@ -852,7 +946,7 @@ private void TryPortMissingExceptionsForMember(DocsMember dMemberToUpdate, Intel
string value = XmlHelper.ReplaceExceptionPatterns(XmlHelper.GetNodesInPlainText(formattedException));
if (!dException.WordCountCollidesAboveThreshold(value, Config.ExceptionCollisionThreshold))
{
AddedExceptions.Add($"Exception=[{tsException.Cref}] in Member=[{dMemberToUpdate.DocId}]");
AddedExceptions.Add($"Exception=[{tsException.Cref.AsEscapedDocId()}] in Member=[{dMemberToUpdate.DocId}]");
dException.AppendException(value);
created = true;
}
Expand Down Expand Up @@ -886,7 +980,7 @@ private bool TryPromptParam(DocsParam oldDParam, IntelliSenseXmlMember tsMember,
int option = -1;
while (option == -1)
{
Log.Error($"Problem in param '{oldDParam.Name}' in member '{tsMember.Name}' in file '{oldDParam.ParentAPI.FilePath}'");
Log.Error($"Problem in param '{oldDParam.Name}' in member '{tsMember.Name.AsEscapedDocId()}' in file '{oldDParam.ParentAPI.FilePath}'");
Log.Error($"The param probably exists in code, but the exact name was not found in Docs. What would you like to do?");
Log.Warning(" 0 - Exit program.");
Log.Info(" 1 - Select the correct IntelliSense xml param from the existing ones.");
Expand Down Expand Up @@ -915,7 +1009,7 @@ private bool TryPromptParam(DocsParam oldDParam, IntelliSenseXmlMember tsMember,
int paramSelection = -1;
while (paramSelection == -1)
{
Log.Info($"IntelliSense xml params found in member '{tsMember.Name}':");
Log.Info($"IntelliSense xml params found in member '{tsMember.Name.AsEscapedDocId()}':");
Log.Warning(" 0 - Exit program.");
Log.Info(" 1 - Ignore this param and continue.");
int paramCounter = 2;
Expand Down Expand Up @@ -991,7 +1085,7 @@ private bool TryPromptTypeParam(DocsTypeParam oldDTypeParam, IntelliSenseXmlMemb
int option = -1;
while (option == -1)
{
Log.Error($"Problem in typeparam '{oldDTypeParam.Name}' in member '{tsMember.Name}' in file '{oldDTypeParam.ParentAPI.FilePath}'");
Log.Error($"Problem in typeparam '{oldDTypeParam.Name}' in member '{tsMember.Name.AsEscapedDocId()}' in file '{oldDTypeParam.ParentAPI.FilePath}'");
Log.Error($"The typeparam probably exists in code, but the exact name was not found in Docs. What would you like to do?");
Log.Warning(" 0 - Exit program.");
Log.Info(" 1 - Select the correct IntelliSense xml typeparam from the existing ones.");
Expand Down Expand Up @@ -1020,7 +1114,7 @@ private bool TryPromptTypeParam(DocsTypeParam oldDTypeParam, IntelliSenseXmlMemb
int typeParamSelection = -1;
while (typeParamSelection == -1)
{
Log.Info($"IntelliSense xml typeparams found in member '{tsMember.Name}':");
Log.Info($"IntelliSense xml typeparams found in member '{tsMember.Name.AsEscapedDocId()}':");
Log.Warning(" 0 - Exit program.");
Log.Info(" 1 - Ignore this typeparam and continue.");
int typeParamCounter = 2;
Expand Down Expand Up @@ -1216,7 +1310,7 @@ void TryPrintMember(ref bool undocMember, string memberDocId)
{
TryPrintMember(ref undocMember, member.DocId);

Log.Error($" Member Exception: {exception.Cref}: {exception.Value}");
Log.Error($" Member Exception: {exception.Cref.AsEscapedDocId()}: {exception.Value}");
exceptions++;
}
}
Expand All @@ -1240,6 +1334,8 @@ private class MissingComments
internal string Returns { get; set; }
internal string Remarks { get; set; }
internal string Property { get; set; }
internal Dictionary<string, string> Params { get; }
internal Dictionary<string, string> TypeParams { get; }
internal bool IsEII { get; set; }

internal MissingComments()
Expand All @@ -1248,6 +1344,8 @@ internal MissingComments()
Returns = Configuration.ToBeAdded;
Remarks = Configuration.ToBeAdded;
Property = Configuration.ToBeAdded;
Params = new Dictionary<string, string>();
TypeParams = new Dictionary<string, string>();
}
}
}
Expand Down
Loading