Different DocIDs between MSDN and Docs

[mairaw]

We're finding some discrepancies on the DocID format for a couple of APIs.

Some examples:

Docs: M:System.Activities.Presentation.Model.ModelItemDictionary.System#Collections#Generic#ICollection<System#Collections#Generic#KeyValuePair<System#Activities#Presentation#Model#ModelItem,System#Activities#Presentation#Model#ModelItem>>#Add(System.Collections.Generic.KeyValuePair{System.Activities.Presentation.Model.ModelItem,System.Activities.Presentation.Model.ModelItem})

MSDN:
M:System.Activities.Presentation.Model.ModelItemDictionary.System#Collections#Generic#ICollection{System#Collections#Generic#KeyValuePair{System#Activities#Presentation#Model#ModelItem@System#Activities#Presentation#Model#ModelItem}}#Add(System.Collections.Generic.KeyValuePair{System.Activities.Presentation.Model.ModelItem,System.Activities.Presentation.Model.ModelItem})
 
Docs: M:System.Collections.Concurrent.ConcurrentDictionary`2.System#Collections#Generic#IDictionary<TKey,TValue>#Add(`0,`1)

MSDN:
M:System.Collections.Concurrent.ConcurrentDictionary`2.System#Collections#Generic#IDictionary{TKey@TValue}#Add(`0,`1)

Docs:
M:Microsoft.VisualBasic.Collection.IListAdd(System.Object)

MSDN:
M:Microsoft.VisualBasic.Collection.System#Collections#IList#Add(System.Object)

[mairaw]

/cc @dend

[dend]

For the above, these are the links for generated ECMAXML that are inconsistent:

• https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Activities.Presentation.Model/ModelItemDictionary.xml#L681
• https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Collections.Concurrent/ConcurrentDictionary%602.xml#L1156
• https://github.com/dotnet/dotnet-api-docs/blob/master/xml/Microsoft.VisualBasic/Collection.xml#L790

cc: @mairaw @joelmartinez

[joelmartinez]

Ok ... so there's a few things to unpack here. I made some sample projects that recreated these types, and had the compiler output the docXML.

1. The first two seem to be using @ as a delimiter between generic instance types on MSDN. I don't know where this is coming from, because csc doesn't use that as the delimiter (and indeed, the only time it does is if the parameter for Add was ref or out, but then the @ was at the end of the parameter type, rather than in between the generic instance types). So for one reason or another, MSDN is using some non-standard form of docid
2. For the 3rd example (IListAdd), this is a VB explicitly implemented member, and I verified that visual studio outputs M:Microsoft.VisualBasic.Collection.IListAdd(System.Object) as the docid. I think this is another instance where MSDN was using non-standard docids
3. On the first one in your list, I verified that mono.cecil uses < and >, instead of { and } for those generic type instances (ie. what you're seeing on docs).

So for 1 and 2 (on my list), I think we're going to have to accept that MSDN was using values that don't align with what the compilers/roslyn is using ... if there's some sort of migration/redirect process that depends on these matching, that system is probably going to have to take these things into account.

For 3 on my list, in the long term, I can open a GH issue on the Mono.Cecil repository to bring this implementation into alignment with roslyn.

[joelmartinez]

For the third on my list ... I've now opened this GH issue on mono.cecil:
jbevain/cecil#528

I will track that item, and incorporate it once the fix makes it in to a new release of mono.cecil.

[dend]

Looks like for (3) you already have a path to resolution @joelmartinez! Thank you for working on this.

[joelmartinez]

I've implemented this fix in mono.cecil, and am now just waiting until it makes it into a released nuget so that I can reference it in a subsequent mdoc release :)