Skip to content

Commit 13fa3eb

Browse files
carlossanlopmairaw
carlossanlop
authored and
mairaw
committed
Port System.Diagnostics source code comments to Docs (#2336)
* Port System.Diagnostics source code comments to Docs * Update Activity.xml Updated a multiline comment based on Will's suggestion. * Apply suggestions from code review Suggested changes by wtgodbe. * Update Activity.xml Removed newline. * Update DiagnosticListener.xml Removed new lines. * Update DiagnosticSource.xml Newlines and link to Write API. * Apply suggestions from code review Suggestions by rpetrusha and mairaw Co-Authored-By: carlossanlop <[email protected]> * Update xml/System.Diagnostics/Activity.xml Co-Authored-By: carlossanlop <[email protected]> * Update xml/System.Diagnostics/Activity.xml Co-Authored-By: carlossanlop <[email protected]> * Update xml/System.Diagnostics/Activity.xml Removing missed summary line * Update Activity.xml Removing an unexpected "list" tag that was missed in a previous suggestion * Update Activity.xml Removing unexpected item element. * Apply suggestions from code review Suggestion I missed by rpetrusha Co-Authored-By: carlossanlop <[email protected]> * Apply suggestions from code review rpetrusha suggestions Co-Authored-By: Ron Petrusha <[email protected]> * Addressed mairaw and rpetrusha more complex suggestions. * Fixed broken xrefs. * Apply suggestions from code review Suggestions by rpetrusha. Co-Authored-By: Ron Petrusha <[email protected]> * Fixed bad xrefs. * Fixed bad xref * minor formatting fixes * more fixes * few more fixes
1 parent c3e74ef commit 13fa3eb

File tree

3 files changed

+316
-112
lines changed

3 files changed

+316
-112
lines changed

‎xml/System.Diagnostics/Activity.xml

Lines changed: 172 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,17 @@
4040
<Parameter Name="operationName" Type="System.String" />
4141
</Parameters>
4242
<Docs>
43-
<param name="operationName">To be added.</param>
44-
<summary>To be added.</summary>
45-
<remarks>To be added.</remarks>
43+
<param name="operationName">The name of the operation.</param>
44+
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Activity" /> class.</summary>
45+
<remarks>
46+
<format type="text/markdown"><![CDATA[
47+
48+
## Remarks
49+
50+
Note that <xref:System.Diagnostics.Activity> has a "builder" pattern: you call the constructor, a number of `Set*` and `Add*` APIs, and then call <xref:System.Diagnostics.Activity.Start> to build the activity. You **must** call <xref:System.Diagnostics.Activity.Start> before using the new instance.
51+
52+
]]></format>
53+
</remarks>
4654
</Docs>
4755
</Member>
4856
<Member MemberName="ActivityTraceFlags">
@@ -89,11 +97,21 @@
8997
<Parameter Name="value" Type="System.String" />
9098
</Parameters>
9199
<Docs>
92-
<param name="key">To be added.</param>
93-
<param name="value">To be added.</param>
94-
<summary>To be added.</summary>
95-
<returns>To be added.</returns>
96-
<remarks>To be added.</remarks>
100+
<param name="key">The baggage key.</param>
101+
<param name="value">The baggage value.</param>
102+
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to have a new baggage item with the specified key and value.</summary>
103+
<returns><see langword="this" /> for convenient chaining.</returns>
104+
<remarks>
105+
<format type="text/markdown"><![CDATA[
106+
107+
## Remarks
108+
109+
This key/value pair is included in the collection returned by the <see cref="P:System.Diagnostics.Activity.Baggage" /> property, and can also be retrieved by the <xref:System.Diagnostics.Activity.GetBaggageItem%2A> method.
110+
111+
`Baggage` is meant for information that is needed for runtime control. For information that is useful to show up in the log with the <xref:System.Diagnostics.Activity>, use the <xref:System.Diagnostics.Activity.Tags> property.
112+
113+
]]></format>
114+
</remarks>
97115
</Docs>
98116
</Member>
99117
<Member MemberName="AddTag">
@@ -119,11 +137,21 @@
119137
<Parameter Name="value" Type="System.String" />
120138
</Parameters>
121139
<Docs>
122-
<param name="key">To be added.</param>
123-
<param name="value">To be added.</param>
124-
<summary>To be added.</summary>
125-
<returns>To be added.</returns>
126-
<remarks>To be added.</remarks>
140+
<param name="key">The tag key.</param>
141+
<param name="value">The tag value.</param>
142+
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to have a new tag with the provided <paramref name="key" /> and <paramref name="value" />. .</summary>
143+
<returns><see langword="this" /> for convenient chaining.</returns>
144+
<remarks>
145+
<format type="text/markdown"><![CDATA[
146+
147+
## Remarks
148+
149+
This key/value pair is included in the collection returned by the <see cref="P:System.Diagnostics.Activity.Tags" /> property.
150+
151+
<xref:System.Diagnostics.Activity.Tags> is meant for information that is useful to log with the <xref:System.Diagnostics.Activity>. For information that is needed for runtime control, use the <xref:System.Diagnostics.Activity.Baggage> property.
152+
153+
]]></format>
154+
</remarks>
127155
</Docs>
128156
</Member>
129157
<Member MemberName="Baggage">
@@ -145,9 +173,17 @@
145173
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;System.String,System.String&gt;&gt;</ReturnType>
146174
</ReturnValue>
147175
<Docs>
148-
<summary>To be added.</summary>
149-
<value>To be added.</value>
150-
<remarks>To be added.</remarks>
176+
<summary>Gets a collection of key/value pairs that represents information that is passed to children of this <see cref="T:System.Diagnostics.Activity" />.</summary>
177+
<value>An enumeration of string-string key-value pairs.</value>
178+
<remarks>
179+
<format type="text/markdown"><![CDATA[
180+
181+
## Remarks
182+
183+
`Baggage` is serialized when requests leave the process (along with the ID). Typically, `Baggage` is used for fine-grained control over logging of the activity and any children. In general, if you are not using the data at runtime, you should be using <xref:System.Diagnostics.Activity.Tags> instead.
184+
185+
]]></format>
186+
</remarks>
151187
</Docs>
152188
</Member>
153189
<Member MemberName="Current">
@@ -169,8 +205,8 @@
169205
<ReturnType>System.Diagnostics.Activity</ReturnType>
170206
</ReturnValue>
171207
<Docs>
172-
<summary>To be added.</summary>
173-
<value>To be added.</value>
208+
<summary>Gets or sets the current operation (<see cref="T:System.Diagnostics.Activity" />) for the current thread. This flows across async calls.</summary>
209+
<value>The current operation for the current thread.</value>
174210
<remarks>To be added.</remarks>
175211
</Docs>
176212
</Member>
@@ -214,8 +250,8 @@
214250
<ReturnType>System.TimeSpan</ReturnType>
215251
</ReturnValue>
216252
<Docs>
217-
<summary>To be added.</summary>
218-
<value>To be added.</value>
253+
<summary>Gets the duration of the operation.</summary>
254+
<value>The delta between <see cref="P:System.Diagnostics.Activity.StartTimeUtc" /> and the end time if the <see cref="T:System.Diagnostics.Activity" /> has ended (<see cref="M:System.Diagnostics.Activity.Stop" /> or <see cref="M:System.Diagnostics.Activity.SetEndTime(System.DateTime)" /> was called), or <see cref="F:System.TimeSpan.Zero"/> if the <see cref="T:System.Diagnostics.Activity" /> has not ended and <see cref="M:System.Diagnostics.Activity.SetEndTime(System.DateTime)" /> was not called.</value>
219255
<remarks>To be added.</remarks>
220256
</Docs>
221257
</Member>
@@ -262,9 +298,9 @@
262298
<Parameter Name="key" Type="System.String" />
263299
</Parameters>
264300
<Docs>
265-
<param name="key">To be added.</param>
266-
<summary>To be added.</summary>
267-
<returns>To be added.</returns>
301+
<param name="key">The baggage key.</param>
302+
<summary>Returns the value of a key-value pair added to the activity with <see cref="M:System.Diagnostics.Activity.AddBaggage(System.String,System.String)" />.</summary>
303+
<returns>The value of the key-value-pair item if it exists, or <see langword="null" /> if it does not exist.</returns>
268304
<remarks>To be added.</remarks>
269305
</Docs>
270306
</Member>
@@ -287,9 +323,17 @@
287323
<ReturnType>System.String</ReturnType>
288324
</ReturnValue>
289325
<Docs>
290-
<summary>To be added.</summary>
291-
<value>To be added.</value>
292-
<remarks>To be added.</remarks>
326+
<summary>Gets an identifier that is specific to a particular request.</summary>
327+
<value>The activity ID.</value>
328+
<remarks>
329+
<format type="text/markdown"><![CDATA[
330+
331+
## Remarks
332+
333+
An ID has a hierarchical structure: `root-id.id1_id2.id3_`. The ID is generated when <xref:System.Diagnostics.Activity.Start> is called by appending a suffix to the `Activity.Parent.Id` or the <xref:System.Diagnostics.Activity.ParentId>. An <xref:System.Diagnostics.Activity> has no ID until it starts. For more information, see [Id Format](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#id-format).
334+
335+
]]></format>
336+
</remarks>
293337
</Docs>
294338
</Member>
295339
<Member MemberName="IdFormat">
@@ -332,9 +376,17 @@
332376
<ReturnType>System.String</ReturnType>
333377
</ReturnValue>
334378
<Docs>
335-
<summary>To be added.</summary>
336-
<value>To be added.</value>
337-
<remarks>To be added.</remarks>
379+
<summary>Gets the operation name.</summary>
380+
<value>The name of the operation.</value>
381+
<remarks>
382+
<format type="text/markdown"><![CDATA[
383+
384+
## Remarks
385+
386+
An operation name is the *coarsest* name that is useful for grouping/filtering. The name is typically a compile-time constant. Names of Rest APIs are reasonable, but arguments (such as specific accounts) should not be in the name but rather in the tags.
387+
388+
]]></format>
389+
</remarks>
338390
</Docs>
339391
</Member>
340392
<Member MemberName="Parent">
@@ -356,8 +408,8 @@
356408
<ReturnType>System.Diagnostics.Activity</ReturnType>
357409
</ReturnValue>
358410
<Docs>
359-
<summary>To be added.</summary>
360-
<value>To be added.</value>
411+
<summary>Gets the parent <see cref="T:System.Diagnostics.Activity" /> that created this activity.</summary>
412+
<value>The parent of this <see cref="T:System.Diagnostics.Activity" />, if it is from the same process, or <see langword="null" /> if this instance has no parent (it is a root activity) or if the parent is from outside the process.</value>
361413
<remarks>To be added.</remarks>
362414
</Docs>
363415
</Member>
@@ -380,9 +432,19 @@
380432
<ReturnType>System.String</ReturnType>
381433
</ReturnValue>
382434
<Docs>
383-
<summary>To be added.</summary>
384-
<value>To be added.</value>
385-
<remarks>To be added.</remarks>
435+
<summary>Gets the ID of this activity's parent.</summary>
436+
<value>The parent ID, if one exists, or <see langword="null" /> if it does not.</value>
437+
<remarks>
438+
<format type="text/markdown"><![CDATA[
439+
440+
## Remarks
441+
442+
If the parent for this <xref:System.Diagnostics.Activity> comes from outside the process, the <xref:System.Diagnostics.Activity> does not have a parent but *may* have a parent ID (which was deserialized from the parent).
443+
444+
This property value can be `null` if this is a root <see cref="T:System.Diagnostics.Activity" /> (i.e. it has no <xref:System.Diagnostics.Activity.Parent>). See [Id Format](href="https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#id-format) for more details.
445+
446+
]]></format>
447+
</remarks>
386448
</Docs>
387449
</Member>
388450
<Member MemberName="ParentSpanId">
@@ -446,9 +508,17 @@
446508
<ReturnType>System.String</ReturnType>
447509
</ReturnValue>
448510
<Docs>
449-
<summary>To be added.</summary>
450-
<value>To be added.</value>
451-
<remarks>To be added.</remarks>
511+
<summary>Gets the root ID of this <see cref="T:System.Diagnostics.Activity" />.</summary>
512+
<value>The root ID, or <see langword="null" /> if the current instance has either a <see cref="P:System.Diagnostics.Activity.ParentId" /> or an <see cref="P:System.Diagnostics.Activity.Id" />.</value>
513+
<remarks>
514+
<format type="text/markdown"><![CDATA[
515+
516+
## Remarks
517+
518+
The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the <xref:System.Diagnostics.Activity.ParentId>) between '|' (or the beginning) and the first `.`. Filtering by root ID allows you to find all activities involved in operation processing. For more information, see [ID Format](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#id-format).
519+
520+
]]></format>
521+
</remarks>
452522
</Docs>
453523
</Member>
454524
<Member MemberName="SetEndTime">
@@ -473,9 +543,9 @@
473543
<Parameter Name="endTimeUtc" Type="System.DateTime" />
474544
</Parameters>
475545
<Docs>
476-
<param name="endTimeUtc">To be added.</param>
477-
<summary>To be added.</summary>
478-
<returns>To be added.</returns>
546+
<param name="endTimeUtc">The UTC stop time.</param>
547+
<summary>Updates the <see cref="T:System.Diagnostics.Activity" /> to set its <see cref="P:System.Diagnostics.Activity.Duration" /> as the difference between <see cref="P:System.Diagnostics.Activity.StartTimeUtc" /> and the specified stop time.</summary>
548+
<returns><see langword="this" /> for convenient chaining.</returns>
479549
<remarks>To be added.</remarks>
480550
</Docs>
481551
</Member>
@@ -501,10 +571,18 @@
501571
<Parameter Name="parentId" Type="System.String" />
502572
</Parameters>
503573
<Docs>
504-
<param name="parentId">To be added.</param>
505-
<summary>To be added.</summary>
506-
<returns>To be added.</returns>
507-
<remarks>To be added.</remarks>
574+
<param name="parentId">The ID of the parent operation.</param>
575+
<summary>Updates this <see cref="T:System.Diagnostics.Activity" /> to indicate that the <see cref="T:System.Diagnostics.Activity" /> with an ID of <paramref name="parentId" /> caused this <see cref="T:System.Diagnostics.Activity" />.</summary>
576+
<returns><see langword="this" /> for convenient chaining.</returns>
577+
<remarks>
578+
<format type="text/markdown"><![CDATA[
579+
580+
## Remarks
581+
582+
This property should only be used in 'boundary' scenarios where an <see cref="T:System.Diagnostics.Activity" /> from another process logically started this <see cref="T:System.Diagnostics.Activity" />. The `parentId` brings up the <xref:System.Diagnostics.Activity.Tags> (as well as the <xref:System.Diagnostics.Activity.ParentId> property) and can be used to reconstruct the causal tree.
583+
584+
]]></format>
585+
</remarks>
508586
</Docs>
509587
</Member>
510588
<Member MemberName="SetParentId">
@@ -556,9 +634,9 @@
556634
<Parameter Name="startTimeUtc" Type="System.DateTime" />
557635
</Parameters>
558636
<Docs>
559-
<param name="startTimeUtc">To be added.</param>
560-
<summary>To be added.</summary>
561-
<returns>To be added.</returns>
637+
<param name="startTimeUtc">The <see cref="T:System.Diagnostics.Activity" /> start time in UTC.</param>
638+
<summary>Sets the start time of this <see cref="T:System.Diagnostics.Activity" />.</summary>
639+
<returns><see langword="this" /> for convenient chaining.</returns>
562640
<remarks>To be added.</remarks>
563641
</Docs>
564642
</Member>
@@ -603,9 +681,23 @@
603681
</ReturnValue>
604682
<Parameters />
605683
<Docs>
606-
<summary>To be added.</summary>
607-
<returns>To be added.</returns>
608-
<remarks>To be added.</remarks>
684+
<summary>Starts the activity.</summary>
685+
<returns><see langword="this" /> for convenient chaining.</returns>
686+
<remarks>
687+
<format type="text/markdown"><![CDATA[
688+
689+
## Remarks
690+
691+
Calling the `Start` method does the following:
692+
- Sets <xref:System.Diagnostics.Activity.Parent> to hold <xref:System.Diagnostics.Activity.Current>.
693+
- Sets <xref:System.Diagnostics.Activity.Current> to this <xref:System.Diagnostics.Activity>.
694+
- If <xref:System.Diagnostics.Activity.StartTimeUtc> was not set previously, sets it to <xref:System.DateTime.UtcNow?displayProperty=nameWithType>.
695+
- Generates a unique <xref:System.Diagnostics.Activity.Id> for this activity.</item>
696+
697+
Use <xref:System.Diagnostics.DiagnosticSource.StartActivity%2A?displayProperty=nameWithType> to start the <see cref="T:System.Diagnostics.Activity" /> and write the start event.
698+
699+
]]></format>
700+
</remarks>
609701
</Docs>
610702
</Member>
611703
<Member MemberName="StartTimeUtc">
@@ -627,9 +719,17 @@
627719
<ReturnType>System.DateTime</ReturnType>
628720
</ReturnValue>
629721
<Docs>
630-
<summary>To be added.</summary>
631-
<value>To be added.</value>
632-
<remarks>To be added.</remarks>
722+
<summary>Gets the time when the operation started.</summary>
723+
<value>The UTC time that the operation started.</value>
724+
<remarks>
725+
<format type="text/markdown"><![CDATA[
726+
727+
## Remarks
728+
729+
The `StartTimeUtc` property is typically initialized when <xref:System.Diagnostics.Activity.Start> is called, but it can be set at any time by calling <xref:System.Diagnostics.Activity.SetStartTime%2A>.
730+
731+
]]></format>
732+
</remarks>
633733
</Docs>
634734
</Member>
635735
<Member MemberName="Stop">
@@ -652,8 +752,22 @@
652752
</ReturnValue>
653753
<Parameters />
654754
<Docs>
655-
<summary>To be added.</summary>
656-
<remarks>To be added.</remarks>
755+
<summary>Stops the activity.</summary>
756+
<remarks>
757+
<format type="text/markdown"><![CDATA[
758+
759+
## Remarks
760+
761+
This information is NOT passed on to the children of this <xref:System.Diagnostics.Activity>.
762+
Calling the `Stop` method:
763+
764+
- Sets <xref:System.Diagnostics.Activity.Current> to <xref:System.Diagnostics.Activity.Parent>.
765+
- If the end time was not set previously, sets <xref:System.Diagnostics.Activity.Duration> as the difference between <xref:System.DateTime.UtcNow?displayProperty=nameWithType> and <xref:System.Diagnostics.Activity.StartTimeUtc>.
766+
767+
Call <xref:System.Diagnostics.DiagnosticSource.StopActivity%2A?displayProperty=nameWithType> to stop the <xref:System.Diagnostics.Activity> and write the stop event.
768+
769+
]]></format>
770+
</remarks>
657771
</Docs>
658772
</Member>
659773
<Member MemberName="Tags">
@@ -675,8 +789,8 @@
675789
<ReturnType>System.Collections.Generic.IEnumerable&lt;System.Collections.Generic.KeyValuePair&lt;System.String,System.String&gt;&gt;</ReturnType>
676790
</ReturnValue>
677791
<Docs>
678-
<summary>To be added.</summary>
679-
<value>To be added.</value>
792+
<summary>Gets a collection of key/value pairs that represent information that will be logged along with the <see cref="T:System.Diagnostics.Activity" /> to the logging system.</summary>
793+
<value>An enumeration of string-string key-value-pairs.</value>
680794
<remarks>To be added.</remarks>
681795
</Docs>
682796
</Member>
@@ -723,4 +837,4 @@
723837
</Docs>
724838
</Member>
725839
</Members>
726-
</Type>
840+
</Type>

0 commit comments

Comments
 (0)