System.Threading.Tasks 1.x undocumented APIs

[carlossanlop]

@tarekgh @stephentoub

Here are the undocumented API from System.Threading.Tasks that were introduced in 1.x.
We are asking all area owners to report back their plan/commitment for their undocumented APIs in order to tackle 33% of the APIs in the next month. Can you please help us with that?

For more information on the plan, see: #3904

Total: 12.
Note: The table has 3 really long columns.

DocId	Source File Path	Docs URL
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList,System#Collections#Generic#IList>>#ConsumeMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2-@System-Collections-Generic-IList-T3----ConsumeMessage
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList,System#Collections#Generic#IList>>#ReleaseReservation(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2-@System-Collections-Generic-IList-T3----ReleaseReservation
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList,System#Collections#Generic#IList>>#ReserveMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2-@System-Collections-Generic-IList-T3----ReserveMessage
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList>>#ConsumeMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2----ConsumeMessage
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList>>#ReleaseReservation(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2----ReleaseReservation
M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<System#Collections#Generic#IList,System#Collections#Generic#IList>>#ReserveMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/BatchedJoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.BatchedJoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-System-Collections-Generic-IList-T1-@System-Collections-Generic-IList-T2----ReserveMessage
M:System.Threading.Tasks.Dataflow.JoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2,T3>>#ConsumeMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2@T3---ConsumeMessage
M:System.Threading.Tasks.Dataflow.JoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2,T3>>#ReleaseReservation(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2@T3---ReleaseReservation
M:System.Threading.Tasks.Dataflow.JoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2,T3>>#ReserveMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`3.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-3.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2@T3---ReserveMessage
M:System.Threading.Tasks.Dataflow.JoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2>>#ConsumeMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2---ConsumeMessage
M:System.Threading.Tasks.Dataflow.JoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2>>#ReleaseReservation(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2---ReleaseReservation
M:System.Threading.Tasks.Dataflow.JoinBlock`2.System#Threading#Tasks#Dataflow#ISourceBlock<System#Tuple<T1,T2>>#ReserveMessage(…	https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading.Tasks.Dataflow/JoinBlock`2.xml	https://review.docs.microsoft.com/en-us/dotnet/api/System.Threading.Tasks.Dataflow.JoinBlock-2.System-Threading-Tasks-Dataflow-ISourceBlock-System-Tuple-T1@T2---ReserveMessage

[stephentoub]

@carlossanlop, most (all?) of these appear to be explicit interface method implementations. We need to document those? There's no public surface area: the API to be documented is on the interface. But even if we do need to, the source is actually documented, it's just using <include/> syntax, e.g. for the first example in your list:
https://github.com/dotnet/runtime/blob/e1441aa7f66c2d21b655549bc7dfdde6340a083e/src/libraries/System.Threading.Tasks.Dataflow/src/Blocks/BatchedJoinBlock.cs#L175-L176
to pull in:
https://github.com/dotnet/runtime/blob/e1441aa7f66c2d21b655549bc7dfdde6340a083e/src/libraries/System.Threading.Tasks.Dataflow/src/XmlDocs/CommonXmlDocComments.xml#L163-L198

[carlossanlop]

@stephentoub yes, EIIs are also documented.

Unfortunately, we have to document them manually, because tags like <include /> or <inherit /> do not copy the original text when building (it's a bug... who should I report this to, the Roslyn team?), so I'm unable to automatically port them with my tool.

The descriptions are copied verbatim from the original API, and in the remarks we add a comment like this:

## Remarks
This member is an explicit interface member implementation. It can be used only when the <xref:DocId.Of.Original.Api> instance is cast to an <xref:DocId.Of.Interface> interface.

Examples we did recently:

• Document System.*IntPtr.Equals (EII) - https://github.com/dotnet/dotnet-api-docs/pull/3647/files
• Document EIIs of integer types (IComparable/IConvertible) - https://github.com/dotnet/dotnet-api-docs/pull/3499/files

[stephentoub]

because tags like <include /> or <inherit /> do not copy the original text when building

I just built System.Threading.Tasks.Dataflow locally, and I see these output correctly in the .xml. Do you see differently?

e.g.

       <member name="M:System.Threading.Tasks.Dataflow.BatchedJoinBlock`3.System#Threading#Tasks#Dataflow#ISourceBlock{System#Tuple{System#Collections#Generic#IList{T1},System#Collections#Generic#IList{T2},System#Collections#Generic#IList{T3}}}#ConsumeMessage(System.Threading.Tasks.Dataflow.DataflowMessageHeader,System.Threading.Tasks.Dataflow.ITargetBlock{System.Tuple{System.Collections.Generic.IList{`0},System.Collections.Generic.IList{`1},System.Collections.Generic.IList{`2}}},System.Boolean@)">
            <summary>
        Passes the ownership of the message identified by the <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> from this 
        <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> instance to the <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" />.  
      </summary><param name="messageHeader">The <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> of the message that is to be consumed.</param><param name="target">
        The <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> for which the message is to be consumed.
      </param><param name="messageConsumed">
        True if the message was successfully consumed. False otherwise.
      </param><returns>
        <para>
          The value of the consumed message. This may correspond to a different <see cref="T:System.Threading.Tasks.Dataflow.DataflowMessageHeader" /> instance than was previously reserved and
          passed as the <paramref name="messageHeader" /> to <see cref="M:ConsumeMessage" />. The consuming <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> must 
          use the returned value instead of the value passed as messageValue through <see cref="M:OfferMessage" />.
        </para>
        <para>
          If the message requested is not available, the return value will be null (Nothing in Visual Basic).
        </para>
      </returns><exception cref="T:System.ArgumentException">
        The <paramref name="messageHeader" /> is not valid.
      </exception><exception cref="T:System.ArgumentNullException">
        The <paramref name="target" /> is null (Nothing in Visual Basic).
      </exception><remarks>
        <para>
          The <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" /> for which the message is to be consumed need not be linked from this 
          <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> instance. Moreover, this <see cref="T:System.Threading.Tasks.Dataflow.ISourceBlock`1" /> 
          instance may have never offered the message directly to the <see cref="T:System.Threading.Tasks.Dataflow.ITargetBlock`1" />. 
        </para>
      </remarks>
        </member>

[carlossanlop]

Glad to hear they are getting copied, and thank you for checking.

I had not tested the tags recently. When I did test the build a couple months ago, I noticed neither of those tags were working. Maybe the issue was noticed and fixed.

Let me try to port them with the DocsPortingTool.