Skip to content

Commit 5484b11

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Automatically port System.Diagnostics triple slash comments (#2671)
* Automatically port System.Diagnostics triple slash comments * Updated through Activities.SpanId. * Update Activity.xml * Update Activity.xml * Update ActivityIdFormat.xml * Update ActivitySpanId.xml * Update ActivityTraceFlags.xml * Update ActivityTraceId.xml * Update ActivityTraceId.xml * Update ActivitySpanId.xml * Update ActivityTraceId.xml * Update DiagnosticListener.xml * Update DiagnosticSource.xml * Update ActivitySpanId.xml * Fixed links
1 parent 95c7531 commit 5484b11

File tree

7 files changed

+242
-101
lines changed

7 files changed

+242
-101
lines changed

‎xml/System.Diagnostics/Activity.xml

Lines changed: 63 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,22 @@
1717
</Base>
1818
<Interfaces />
1919
<Docs>
20-
<summary>To be added.</summary>
21-
<remarks>To be added.</remarks>
20+
<summary>Represents an operation with context to be used for logging.</summary>
21+
<remarks>
22+
<format type="text/markdown"><![CDATA[
23+
24+
An `Activity` has an operation name, an ID, a start time and duration, tags, and baggage.
25+
26+
The current activity can be accessed with the static <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType> property.
27+
28+
Activities should be created by calling the constructor, configured as necessary, and then started with the <xref:System.Diagnostics.Activity.Start%2A> method, which maintains parent-child relationships for the activities and sets <xref:System.Diagnostics.Activity.Current?displayProperty=nameWithType>.
29+
30+
When an activity is finished, it should be stopped with the <xref:System.Diagnostics.Activity.Stop?displayProperty=nameWithType> method.
31+
32+
No `Activity` methods allow exceptions to escape as a response to bad inputs. They are thrown and caught (which allows debuggers and monitors to see the error), but the exception is suppressed, and the operation does something reasonable (typically it does nothing).
33+
34+
]]></format>
35+
</remarks>
2236
</Docs>
2337
<Members>
2438
<Member MemberName=".ctor">
@@ -69,8 +83,8 @@ Note that <xref:System.Diagnostics.Activity> has a "builder" pattern: you call t
6983
<ReturnType>System.Diagnostics.ActivityTraceFlags</ReturnType>
7084
</ReturnValue>
7185
<Docs>
72-
<summary>To be added.</summary>
73-
<value>To be added.</value>
86+
<summary>Gets the flags (defined by the W3C ID specification) associated with the activity.</summary>
87+
<value>the flags associated with the activity.</value>
7488
<remarks>To be added.</remarks>
7589
</Docs>
7690
</Member>
@@ -228,9 +242,15 @@ This key/value pair is included in the collection returned by the <see cref="P:S
228242
<ReturnType>System.Diagnostics.ActivityIdFormat</ReturnType>
229243
</ReturnValue>
230244
<Docs>
231-
<summary>To be added.</summary>
245+
<summary>Gets or sets the default ID format for the <see cref="T:System.Diagnostics.Activity" />.</summary>
232246
<value>To be added.</value>
233-
<remarks>To be added.</remarks>
247+
<remarks>
248+
<format type="text/markdown"><![CDATA[
249+
250+
The `Activity` instance tries to use the same format for IDs as its parent. If the activity has no parent, this property determines the default format to use.
251+
252+
]]></format>
253+
</remarks>
234254
</Docs>
235255
</Member>
236256
<Member MemberName="Duration">
@@ -273,9 +293,15 @@ This key/value pair is included in the collection returned by the <see cref="P:S
273293
<ReturnType>System.Boolean</ReturnType>
274294
</ReturnValue>
275295
<Docs>
276-
<summary>To be added.</summary>
277-
<value>To be added.</value>
278-
<remarks>To be added.</remarks>
296+
<summary>Gets or sets a valud that detrmines if the <see cref="P:System.Diagnostics.Activity.DefaultIdFormat" /> is always used to define the default ID format. </summary>
297+
<value><see langword="true" /> to always use the <see cref="P:System.Diagnostics.Activity.DefaultIdFormat" />; otherwise, <see langword= "false" />.</value>
298+
<remarks>
299+
<format type="text/markdown"><![CDATA[
300+
301+
Normally if the <xref:System.Diagnostics.Activity.ParentId> is defined, its format determines the format used by the current <xref:System.Diagnostics.Activity>. However, if `ForceDefaultFormat` is set to `true`, the ID format is always defined by the <xref:System.Diagnostics.Activity.DefaultIdFormat> property even if the <xref:System.Diagnostics.Activity.ParentID> is defined and the parent has a different format.
302+
303+
]]></format>
304+
</remarks>
279305
</Docs>
280306
</Member>
281307
<Member MemberName="GetBaggageItem">
@@ -354,8 +380,8 @@ An ID has a hierarchical structure: `root-id.id1_id2.id3_`. The ID is generated
354380
<ReturnType>System.Diagnostics.ActivityIdFormat</ReturnType>
355381
</ReturnValue>
356382
<Docs>
357-
<summary>To be added.</summary>
358-
<value>To be added.</value>
383+
<summary>Gets the format for the <see cref="P:System.Diagnostics.Activity.Id" />.</summary>
384+
<value>The format for the <see cref="P:System.Diagnostics.Activity.Id" />.</value>
359385
<remarks>To be added.</remarks>
360386
</Docs>
361387
</Member>
@@ -465,9 +491,15 @@ This property value can be `null` if this is a root <see cref="T:System.Diagnost
465491
<ReturnType>System.Diagnostics.ActivitySpanId</ReturnType>
466492
</ReturnValue>
467493
<Docs>
468-
<summary>To be added.</summary>
469-
<value>To be added.</value>
470-
<remarks>To be added.</remarks>
494+
<summary>Gets the parent's <see cref="P:System.Diagnostics.Activity.SpanId" />.</summary>
495+
<value>The parent's <see cref="P:System.Diagnostics.Activity.SpanId" />.</value>
496+
<remarks>
497+
<format type="text/markdown"><![CDATA[
498+
499+
If the <xref:System.Diagnostics.Activity.ParentId?displayProperty=nameWithType> is in the W3C format, this property returns the <xref:System.Diagnostics.Activity.SpanId> part of the ParentId. Otherwise it returns a zero <xref:System.Diagnostics.Activity.SpanId>.
500+
501+
]]></format>
502+
</remarks>
471503
</Docs>
472504
</Member>
473505
<Member MemberName="Recorded">
@@ -486,8 +518,8 @@ This property value can be `null` if this is a root <see cref="T:System.Diagnost
486518
<ReturnType>System.Boolean</ReturnType>
487519
</ReturnValue>
488520
<Docs>
489-
<summary>To be added.</summary>
490-
<value>To be added.</value>
521+
<summary>Gets a value that indicates whether the W3CIdFlags.Recorded flag is set.</summary>
522+
<value><see langword="true" /> if the W3CIdFlags.Recorded flag is set; otherwise, <see langword="false" />.</value>
491523
<remarks>To be added.</remarks>
492524
</Docs>
493525
</Member>
@@ -661,8 +693,8 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
661693
<ReturnType>System.Diagnostics.ActivitySpanId</ReturnType>
662694
</ReturnValue>
663695
<Docs>
664-
<summary>To be added.</summary>
665-
<value>To be added.</value>
696+
<summary>Gets the SPAN part of the <see cref="P:System.Diagnostics.Activity.Id" />.</summary>
697+
<value>The ID for the SPAN part of <see cref="P:System.Diagnostics.Activity.Id" />, if the <see cref="T:System.Diagnostics.Activity" /> has the W3C format; otherwise, a zero <see langword="SpanId" />.</value>
666698
<remarks>To be added.</remarks>
667699
</Docs>
668700
</Member>
@@ -816,8 +848,8 @@ Call <xref:System.Diagnostics.DiagnosticSource.StopActivity%2A?displayProperty=n
816848
<ReturnType>System.Diagnostics.ActivityTraceId</ReturnType>
817849
</ReturnValue>
818850
<Docs>
819-
<summary>To be added.</summary>
820-
<value>To be added.</value>
851+
<summary>Gets the TraceId part of the <see cref="P:System.Diagnostics.Activity.Id" />.</summary>
852+
<value>The ID for the TraceId part of the <see cref="P:System.Diagnostics.Activity.Id" />, if the ID has the W3C format; otherwise, a zero TraceId.</value>
821853
<remarks>To be added.</remarks>
822854
</Docs>
823855
</Member>
@@ -837,9 +869,17 @@ Call <xref:System.Diagnostics.DiagnosticSource.StopActivity%2A?displayProperty=n
837869
<ReturnType>System.String</ReturnType>
838870
</ReturnValue>
839871
<Docs>
840-
<summary>To be added.</summary>
841-
<value>To be added.</value>
842-
<remarks>To be added.</remarks>
872+
<summary>Gets the W3C <see langword="tracestate" /> header.</summary>
873+
<value>The W3C <see langword="tracestate" /> header.</value>
874+
<remarks>
875+
<format type="text/markdown"><![CDATA[
876+
877+
The `tracestate` header is intended to carry supplemental information to trace identity contained in the trace parent. `tracestate` consists of a list of key/value pairs that convey information about the request position in multiple distributed tracing graphs. This information is typically used by distributed tracing systems and should not be used for general purpose baggage, since this may break the correlation of a distributed trace.
878+
879+
Logically `TraceStateString` is just a kind of baggage (if flows just like baggage), but because it is expected to be special-cased (it has its own HTTP header), it is more convenient/efficient if it is not lumped in with other baggage.
880+
881+
]]></format>
882+
</remarks>
843883
</Docs>
844884
</Member>
845885
</Members>

‎xml/System.Diagnostics/ActivityIdFormat.xml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
<BaseTypeName>System.Enum</BaseTypeName>
1414
</Base>
1515
<Docs>
16-
<summary>To be added.</summary>
16+
<summary>Specifies the format of the <see cref="P:System.Diagnostics.Activity.Id" /> property.</summary>
1717
<remarks>To be added.</remarks>
1818
</Docs>
1919
<Members>
@@ -34,7 +34,7 @@
3434
</ReturnValue>
3535
<MemberValue>1</MemberValue>
3636
<Docs>
37-
<summary>To be added.</summary>
37+
<summary>The hierarchical format.</summary>
3838
</Docs>
3939
</Member>
4040
<Member MemberName="Unknown">
@@ -54,7 +54,7 @@
5454
</ReturnValue>
5555
<MemberValue>0</MemberValue>
5656
<Docs>
57-
<summary>To be added.</summary>
57+
<summary>An unknown format.</summary>
5858
</Docs>
5959
</Member>
6060
<Member MemberName="W3C">
@@ -74,8 +74,8 @@
7474
</ReturnValue>
7575
<MemberValue>2</MemberValue>
7676
<Docs>
77-
<summary>To be added.</summary>
77+
<summary>The W3C format.</summary>
7878
</Docs>
7979
</Member>
8080
</Members>
81-
</Type>
81+
</Type>

‎xml/System.Diagnostics/ActivitySpanId.xml

Lines changed: 43 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,16 @@
1818
</Interface>
1919
</Interfaces>
2020
<Docs>
21-
<summary>To be added.</summary>
22-
<remarks>To be added.</remarks>
21+
<summary>Represents a <see cref="P:System.Diagnostics.Activity.SpanId" /> formatted based on a W3C standard.</summary>
22+
<remarks>
23+
<format type="text/markdown"><![CDATA[
24+
25+
The `ActivitySpanId` structure reflects the format that the W3C standard requires for the ID of a single span in a trace. It consists of 8 bytes, typically displayed as 16 hexadecimal characters. An `ActivitySpanId` is returned by the <xref:System.Diagnostics.Activity.SpanId?displayProperty=nameWithtype> for an <xref:System.Diagnostics.Activity> whose <xref:System.Diagnostics.Activity.IdFormat?displayProperty=nameWithType> is <xref:System.Diagnostics.ActivityIdFormat.W3C?displayProperty=nameWithtype>.
26+
27+
Because an `ActivitySpanId` is a structure that contains 8 bytes, it can be passed by reference. `ActivitySpanId` contains methods for converting to and from hexadecimal string representation, tries to avoid changing formats until it has to, and caches its string representation after it is created. It is mostly useful as an exchange type.
28+
29+
]]></format>
30+
</remarks>
2331
</Docs>
2432
<Members>
2533
<Member MemberName="CopyTo">
@@ -41,8 +49,8 @@
4149
<Parameter Name="destination" Type="System.Span&lt;System.Byte&gt;" />
4250
</Parameters>
4351
<Docs>
44-
<param name="destination">To be added.</param>
45-
<summary>To be added.</summary>
52+
<param name="destination">The span to which the 8 bytes of the SpanID are to be copied.</param>
53+
<summary>Copies the 8 bytes of the current <see cref="T:System.Diagnostics.ActivitySpanId" /> to a specified span.</summary>
4654
<remarks>To be added.</remarks>
4755
</Docs>
4856
</Member>
@@ -65,10 +73,11 @@
6573
<Parameter Name="idData" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
6674
</Parameters>
6775
<Docs>
68-
<param name="idData">To be added.</param>
69-
<summary>To be added.</summary>
70-
<returns>To be added.</returns>
76+
<param name="idData">A read-only span of eight bytes.</param>
77+
<summary>Creates a new <see cref="T:System.Diagnostics.ActivitySpanId" /> value from a read-only span of eight bytes.</summary>
78+
<returns>The new span ID.</returns>
7179
<remarks>To be added.</remarks>
80+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="idData" /> does not contain eight bytes.</exception>
7281
</Docs>
7382
</Member>
7483
<Member MemberName="CreateFromString">
@@ -90,10 +99,23 @@
9099
<Parameter Name="idData" Type="System.ReadOnlySpan&lt;System.Char&gt;" />
91100
</Parameters>
92101
<Docs>
93-
<param name="idData">To be added.</param>
94-
<summary>To be added.</summary>
95-
<returns>To be added.</returns>
96-
<remarks>To be added.</remarks>
102+
<param name="idData">A span that contains 16 hexadecimal characters.</param>
103+
<summary>Creates a new <see cref="T:System.Diagnostics.ActivitySpanId" /> value from a read-only span of 16 hexadecimal characters.</summary>
104+
<returns>The new span ID.</returns>
105+
<remarks>
106+
<format type="text/markdown"><![CDATA[
107+
108+
`idData` can consist either of numbers and lower-case hexadecimal characters or of all zeros.
109+
110+
]]></format>
111+
</remarks>
112+
<exception cref="T:System.ArgumentOutOfRangeException"><paramref name="idData" /> does not contain 16 hexadecimal characters.
113+
114+
-or-
115+
116+
The characters in <paramref name="idData" /> are not all lower-case hexadecimal characters or all zeros.
117+
118+
</exception>
97119
</Docs>
98120
</Member>
99121
<Member MemberName="CreateFromUtf8String">
@@ -115,9 +137,9 @@
115137
<Parameter Name="idData" Type="System.ReadOnlySpan&lt;System.Byte&gt;" />
116138
</Parameters>
117139
<Docs>
118-
<param name="idData">To be added.</param>
119-
<summary>To be added.</summary>
120-
<returns>To be added.</returns>
140+
<param name="idData">A read-only span of UTF8-encoded bytes.</param>
141+
<summary>Creates a new <see cref="T:System.Diagnostics.ActivitySpanId" /> value from a read-only span of UTF8-encoded bytes.</summary>
142+
<returns>The new span ID.</returns>
121143
<remarks>To be added.</remarks>
122144
</Docs>
123145
</Member>
@@ -138,8 +160,8 @@
138160
</ReturnValue>
139161
<Parameters />
140162
<Docs>
141-
<summary>To be added.</summary>
142-
<returns>To be added.</returns>
163+
<summary>Creates a new <see cref="T:System.Diagnostics.ActivitySpanId" /> based on a random number (that is very likely to be unique).</summary>
164+
<returns>The new span ID.</returns>
143165
<remarks>To be added.</remarks>
144166
</Docs>
145167
</Member>
@@ -289,8 +311,8 @@
289311
</ReturnValue>
290312
<Parameters />
291313
<Docs>
292-
<summary>To be added.</summary>
293-
<returns>To be added.</returns>
314+
<summary>Returns a 16-character hexadecimal string that represents this span ID.</summary>
315+
<returns>The 16-character hecxadecimal string representation of this span ID.</returns>
294316
<remarks>To be added.</remarks>
295317
</Docs>
296318
</Member>
@@ -311,10 +333,10 @@
311333
</ReturnValue>
312334
<Parameters />
313335
<Docs>
314-
<summary>To be added.</summary>
315-
<returns>To be added.</returns>
336+
<summary>Returns a 16-character hexadecimal string that represents this span ID.</summary>
337+
<returns>The 16-character hexadecimal string representation of this span ID.</returns>
316338
<remarks>To be added.</remarks>
317339
</Docs>
318340
</Member>
319341
</Members>
320-
</Type>
342+
</Type>

‎xml/System.Diagnostics/ActivityTraceFlags.xml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,14 @@
1818
</Attribute>
1919
</Attributes>
2020
<Docs>
21-
<summary>To be added.</summary>
22-
<remarks>To be added.</remarks>
21+
<summary>Specifies flags defined by the W3C standard that are associated with an activity.</summary>
22+
<remarks>
23+
<format type="text/markdown"><![CDATA[
24+
25+
An `ActivityTraceFflags` value is returned by the <xref:System.Diagnostics.Activity.ActivityTraceFlags?displayProperty=nameWithtype> property.
26+
27+
]]></format>
28+
</remarks>
2329
</Docs>
2430
<Members>
2531
<Member MemberName="None">
@@ -63,4 +69,4 @@
6369
</Docs>
6470
</Member>
6571
</Members>
66-
</Type>
72+
</Type>

0 commit comments

Comments
 (0)