Added documentation for System.Diagnostics APIs targeted for 3.0 (dotnet#2969)

jozkee · mairaw · commit f0002bff6090 · 2019-08-08T17:00:38.000-07:00
* Added documentation for System.Diagnostics APIs targeted for 3.0

* Apply suggestions from code review

Co-Authored-By: Ron Petrusha &lt;ronpet@microsoft.com&gt;
Co-Authored-By: Carlos Sanchez Lopez &lt;1175054+carlossanlop@users.noreply.github.com&gt;

* Update Activity.xml

* fix broken link
diff --git a/xml/System.Diagnostics/Activity.xml b/xml/System.Diagnostics/Activity.xml
@@ -604,10 +604,18 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
         <Parameter Name="format" Type="System.Diagnostics.ActivityIdFormat" Index="0" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="format">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="format">One of the enumeration values that specifies the format of the <see cref="P:System.Diagnostics.Activity.Id" /> property.</param>
+        <summary>Sets the ID format on this <see cref="T:System.Diagnostics.Activity" /> before it is started.</summary>
+        <returns><see langword="this" /> for convenient chaining.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+## Remarks
+
+The specified format will take precedence over `Parent.IdFormat`, the <xref:System.Diagnostics.Activity.ParentId> format, <xref:System.Diagnostics.Activity.DefaultIdFormat>, and <xref:System.Diagnostics.Activity.ForceDefaultIdFormat>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="SetParentId">
@@ -667,7 +675,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
       <Docs>
         <param name="traceId">The parent activity's TraceId.</param>
         <param name="spanId">The parent activity's SpanId.</param>
-        <param name="activityTraceFlags">To be added.</param>
+        <param name="activityTraceFlags">One of the enumeration values that specifies flags defined by the W3C standard that are associated with an activity.</param>
         <summary>Sets the parent ID using the W3C convention of a TraceId and a SpanId.</summary>
         <returns><see langword="this" /> for convenient chaining.</returns>
         <remarks>
diff --git a/xml/System.Diagnostics/DiagnosticListener.xml b/xml/System.Diagnostics/DiagnosticListener.xml
@@ -439,10 +439,10 @@ If `isEnabled` is `null`, no filtering is done (all overloads of <xref:System.Di
         <Parameter Name="onActivityExport" Type="System.Action&lt;System.Diagnostics.Activity,System.Object&gt;" Index="3" FrameworkAlternate="netcore-3.0" />
       </Parameters>
       <Docs>
-        <param name="observer">To be added.</param>
-        <param name="isEnabled">To be added.</param>
-        <param name="onActivityImport">To be added.</param>
-        <param name="onActivityExport">To be added.</param>
+        <param name="observer">A subscriber.</param>
+        <param name="isEnabled">A delegate that filters events based on their name and up to two context objects (which can be <see langword="null" />), or <see langword="null" /> if an event filter is not desirable.</param>
+        <param name="onActivityImport">An action delegate that receives the activity affected by an external event and an object that represents the incoming request.</param>
+        <param name="onActivityExport">An action delegate that receives the activity affected by an external event and an object that represents the outgoing request.</param>
         <summary>Adds a subscriber, optionally filters events based on their name and up to two context objects, and specifies methods to call when providers import or export activites from outside the process.</summary>
         <returns>A reference to an interface that allows the listener to stop receiving notifications before the <see cref="T:System.Diagnostics.DiagnosticSource" /> has finished sending them.</returns>
         <remarks>
@@ -525,4 +525,4 @@ For more information, see the <xref:System.Diagnostics.DiagnosticSource.Write%2A
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>
