[mdoc] Group overloads and allow information related to all of them

[dend]

One of the scenarios that we are encountering is the need to associate certain information with all overloads of a member. For example:

https://msdn.microsoft.com/en-us/library/system.string.compare(v=vs.110).aspx

Notice that there is a description associated with the set of overloads. This is something that is not possible today in ECMAXML as it does not allow descriptions for member sets, or even the grouping of members.

The ask is to allow member grouping per-name (e.g. find overloads of a method) and then allow information to be presented within that group.

[joelmartinez]

Two potential approaches, based on a chat convo with @dend ... documenting for discussion:

Multiple <Member> Nodes

Would allow for manual grouping of nodes ... you could add a common remarks section that would be rendered first for all member nodes. Something like

<Members>
    <remarks>...</remarks>
    <Member Name="foo">...</Member>
     ...
</Members>
<Members>
    <remarks>...</remarks>
    <Member Name="bar">...</Member>
    ...
</Members>

A New <MemberGroup> Node

A node that would represent common information about a set of overloads

<Members>
    <MemberGroup Name="foo">...</MemberGroup>
    <Member Name="foo">...</Member>
    <Member Name="foo">...</Member>
</Members>

[jonpryor]

I'm partial to the <MemberGroup/> idea.

That said, I'm conflicted. Consider the all-important String.Format() method. Notice that:

1. The documentation for the method overload page is huge; the method overload page is the documentation, for most intents and purposes.
2. The documentation for an individual method, such as String.Format(IFormatProvider, String, Object), is (a) comparatively very short, and (b) has a See Also link to the Format Overload documentation.

These things together mean that not only do we need to provide a way to document overloads, but we need a way to link to the overload section itself.

I'm not at all sure how to do that. A "logical" thing to do would be to use no parenthesis with an M: "url", e.g. <see cref="M:System.String.Format" />, but this syntax has already been "taken" in monodoc.dll, and would result in a link to a 0-parameter System.String.Format() method (which doesn't exist).

We could "break API" and state that, going forward, no-parenthesis method references direct to the method overload documentation, but I fear that this would be a huge break with untold impact.

...though perhaps that wouldn't actually matter that much, so long as the overload list allows selecting the 0-parameter overload, so at worse it would just be an extra click for the user.

The more I write this down, the more it seems plausibly acceptable.

If we don't "break" syntax, we need to introduce another. I fear that much code assumes that the "member prefix" is a single character, so using MG:System.String.Format may likewise prove problematic. Perhaps we could use G, for Group, allowing G:System.String.Format as a CREF to the string.Format() overloads list? (O is used for Operator.)

[joelmartinez]

@dend Since you are importing existing content into the EcmaXML format, I'm going to partially defer this enhancement. For the purpose of v5.0 Preview, I'll modify the schema in #35, which will allow the element in your imported data set, along with any enhancements required (not sure if any, I'll test) to make sure that mdoc update leaves those MemberGroup intact :)

[dend]

@joelmartinez is this an expensive item? It would definitely make life easier in terms of generated content and showing everything from one method in one place.

[joelmartinez]

@dend It's not necessarily expensive, just that the remaining item is really just around rendering for existing monodoc clients ... something which you won't be using, which is why I chose to create a different GH issue to capture just the usage requirements that you need for this release (in PR#36). Want to make sure I finish Milestone 1 with enough time for your team to do your work :)

[joelmartinez]

Not sure how this item never got closed … but MemberGroup was added a while ago :)