Skip to content

Commit f4d6991

Browse files
carlossanlopcarlossanlop
authored
Port System.Diagnostics.Metrics new docs (second pass) (#10215)
* System.Diagnostics.Metrics
1 parent f8b0e7e commit f4d6991

File tree

5 files changed

+76
-63
lines changed

5 files changed

+76
-63
lines changed

‎xml/System.Diagnostics.Metrics/Gauge`1.xml

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@
2727
<Interfaces />
2828
<Docs>
2929
<typeparam name="T">To be added.</typeparam>
30-
<summary>To be added.</summary>
31-
<remarks>To be added.</remarks>
30+
<summary>The Gauge is an instrument used to record non-additive values whenever changes occur. For example, record the room background noise level value when changes occur.</summary>
31+
<remarks>This class supports only the following generic parameter types: <see cref="T:System.Byte" />, <see cref="T:System.Int16" />, <see cref="T:System.Int32" />, <see cref="T:System.Int64" />, <see cref="T:System.Single" />, <see cref="T:System.Double" />, and <see cref="T:System.Decimal" /></remarks>
3232
</Docs>
3333
<Members>
3434
<Member MemberName="Record">
@@ -50,8 +50,8 @@
5050
<Parameter Name="value" Type="T" />
5151
</Parameters>
5252
<Docs>
53-
<param name="value">To be added.</param>
54-
<summary>To be added.</summary>
53+
<param name="value">The Gauge current value.</param>
54+
<summary>Record the Gauge current value.</summary>
5555
<remarks>To be added.</remarks>
5656
</Docs>
5757
</Member>
@@ -82,9 +82,9 @@
8282
</Parameter>
8383
</Parameters>
8484
<Docs>
85-
<param name="value">To be added.</param>
86-
<param name="tag">To be added.</param>
87-
<summary>To be added.</summary>
85+
<param name="value">The Gauge current value.</param>
86+
<param name="tag">A key-value pair tag associated with the measurement.</param>
87+
<summary>Record the Gauge current value.</summary>
8888
<remarks>To be added.</remarks>
8989
</Docs>
9090
</Member>
@@ -119,9 +119,9 @@
119119
</Parameter>
120120
</Parameters>
121121
<Docs>
122-
<param name="value">To be added.</param>
123-
<param name="tags">To be added.</param>
124-
<summary>To be added.</summary>
122+
<param name="value">The Gauge current value.</param>
123+
<param name="tags">A list of key-value pair tags associated with the measurement.</param>
124+
<summary>Record the Gauge current value.</summary>
125125
<remarks>To be added.</remarks>
126126
</Docs>
127127
</Member>
@@ -152,9 +152,9 @@
152152
</Parameter>
153153
</Parameters>
154154
<Docs>
155-
<param name="value">To be added.</param>
156-
<param name="tagList">To be added.</param>
157-
<summary>To be added.</summary>
155+
<param name="value">The Gauge current value.</param>
156+
<param name="tagList">A <see cref="T:System.Diagnostics.TagList" /> of tags associated with the measurement.</param>
157+
<summary>Record the Gauge current value.</summary>
158158
<remarks>To be added.</remarks>
159159
</Docs>
160160
</Member>
@@ -193,9 +193,9 @@
193193
</Parameter>
194194
</Parameters>
195195
<Docs>
196-
<param name="value">To be added.</param>
197-
<param name="tags">To be added.</param>
198-
<summary>To be added.</summary>
196+
<param name="value">The Gauge current value.</param>
197+
<param name="tags">A span of key-value pair tags associated with the measurement.</param>
198+
<summary>Record the Gauge current value.</summary>
199199
<remarks>To be added.</remarks>
200200
</Docs>
201201
</Member>
@@ -234,10 +234,10 @@
234234
</Parameter>
235235
</Parameters>
236236
<Docs>
237-
<param name="value">To be added.</param>
238-
<param name="tag1">To be added.</param>
239-
<param name="tag2">To be added.</param>
240-
<summary>To be added.</summary>
237+
<param name="value">The Gauge current value.</param>
238+
<param name="tag1">A first key-value pair tag associated with the measurement.</param>
239+
<param name="tag2">A second key-value pair tag associated with the measurement.</param>
240+
<summary>Record the Gauge current value.</summary>
241241
<remarks>To be added.</remarks>
242242
</Docs>
243243
</Member>
@@ -284,11 +284,11 @@
284284
</Parameter>
285285
</Parameters>
286286
<Docs>
287-
<param name="value">To be added.</param>
288-
<param name="tag1">To be added.</param>
289-
<param name="tag2">To be added.</param>
290-
<param name="tag3">To be added.</param>
291-
<summary>To be added.</summary>
287+
<param name="value">The Gauge current value.</param>
288+
<param name="tag1">A first key-value pair tag associated with the measurement.</param>
289+
<param name="tag2">A second key-value pair tag associated with the measurement.</param>
290+
<param name="tag3">A third key-value pair tag associated with the measurement.</param>
291+
<summary>Record the Gauge current value.</summary>
292292
<remarks>To be added.</remarks>
293293
</Docs>
294294
</Member>

‎xml/System.Diagnostics.Metrics/Instrument.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,9 @@
4848
<Parameter Name="name" Type="System.String" Index="1" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
4949
</Parameters>
5050
<Docs>
51-
<param name="meter">To be added.</param>
52-
<param name="name">To be added.</param>
53-
<summary>To be added.</summary>
51+
<param name="meter">The meter that created the instrument. Cannot be <see langword="null" />.</param>
52+
<param name="name">The instrument name. Cannot be <see langword="null" />.</param>
53+
<summary>Constructs a new instance of <see cref="T:System.Diagnostics.Metrics.Instrument" />.</summary>
5454
<remarks>To be added.</remarks>
5555
</Docs>
5656
</Member>

‎xml/System.Diagnostics.Metrics/InstrumentAdvice`1.xml

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@
2323
</Base>
2424
<Interfaces />
2525
<Docs>
26-
<typeparam name="T">To be added.</typeparam>
27-
<summary>To be added.</summary>
26+
<typeparam name="T">Instrument value type.</typeparam>
27+
<summary>Contains configuration settings advised to be used by metrics consumers when recording measurements for a given <see cref="T:System.Diagnostics.Metrics.Instrument`1" />.</summary>
2828
<remarks>To be added.</remarks>
2929
</Docs>
3030
<Members>
@@ -41,7 +41,7 @@
4141
</AssemblyInfo>
4242
<Parameters />
4343
<Docs>
44-
<summary>To be added.</summary>
44+
<summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Metrics.InstrumentAdvice`1" /> class.</summary>
4545
<remarks>To be added.</remarks>
4646
</Docs>
4747
</Member>
@@ -67,9 +67,16 @@
6767
<ReturnType>System.Collections.Generic.IReadOnlyList&lt;T&gt;</ReturnType>
6868
</ReturnValue>
6969
<Docs>
70-
<summary>To be added.</summary>
70+
<summary>Gets the explicit bucket boundaries advised to be used with histogram instruments.</summary>
7171
<value>To be added.</value>
72-
<remarks>To be added.</remarks>
72+
<remarks>
73+
<para>Notes:</para>
74+
<list type="bullet">
75+
<item>A <see langword="null" /> value means no bucket boundaries have been configured and default values should be used for bucket configuration.</item>
76+
<item>An empty set of bucket boundaries hints that the histogram by default should NOT contain buckets and should only track count and sum values.</item>
77+
<item>A set of distinct increasing values for bucket boundaries hints that the histogram should use those for its default bucket configuration.</item>
78+
</list>
79+
</remarks>
7380
</Docs>
7481
</Member>
7582
</Members>

‎xml/System.Diagnostics.Metrics/Instrument`1.xml

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,9 @@ This class supports only the following generic parameter types: <xref:System.Byt
6868
<Parameter Name="name" Type="System.String" Index="1" FrameworkAlternate="net-8.0;net-9.0;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0" />
6969
</Parameters>
7070
<Docs>
71-
<param name="meter">To be added.</param>
72-
<param name="name">To be added.</param>
73-
<summary>To be added.</summary>
71+
<param name="meter">The meter that created the instrument. Cannot be <see langword="null" />.</param>
72+
<param name="name">The instrument name. Cannot be <see langword="null" />.</param>
73+
<summary>Constructs a new instance of <see cref="T:System.Diagnostics.Metrics.Instrument`1" />.</summary>
7474
<remarks>To be added.</remarks>
7575
</Docs>
7676
</Member>
@@ -241,13 +241,13 @@ This class supports only the following generic parameter types: <xref:System.Byt
241241
</Parameter>
242242
</Parameters>
243243
<Docs>
244-
<param name="meter">To be added.</param>
245-
<param name="name">To be added.</param>
246-
<param name="unit">To be added.</param>
247-
<param name="description">To be added.</param>
248-
<param name="tags">To be added.</param>
249-
<param name="advice">To be added.</param>
250-
<summary>To be added.</summary>
244+
<param name="meter">The meter that created the instrument. Cannot be <see langword="null" />.</param>
245+
<param name="name">The instrument name. Cannot be <see langword="null" />.</param>
246+
<param name="unit">Optional instrument unit of measurements.</param>
247+
<param name="description">Optional instrument description.</param>
248+
<param name="tags">Optional instrument tags.</param>
249+
<param name="advice">Optional <see cref="T:System.Diagnostics.Metrics.InstrumentAdvice`1" />.</param>
250+
<summary>Constructs a new instance of <see cref="T:System.Diagnostics.Metrics.Instrument`1" />.</summary>
251251
<remarks>To be added.</remarks>
252252
</Docs>
253253
</Member>
@@ -273,7 +273,7 @@ This class supports only the following generic parameter types: <xref:System.Byt
273273
<ReturnType>System.Diagnostics.Metrics.InstrumentAdvice&lt;T&gt;</ReturnType>
274274
</ReturnValue>
275275
<Docs>
276-
<summary>To be added.</summary>
276+
<summary>Gets the <see cref="T:System.Diagnostics.Metrics.InstrumentAdvice`1" /> associated with the instrument.</summary>
277277
<value>To be added.</value>
278278
<remarks>To be added.</remarks>
279279
</Docs>

‎xml/System.Diagnostics.Metrics/Meter.xml

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -360,10 +360,13 @@ Counter is an instrument that supports non-negative increments. Example uses for
360360
</Parameters>
361361
<Docs>
362362
<typeparam name="T">To be added.</typeparam>
363-
<param name="name">To be added.</param>
364-
<summary>To be added.</summary>
363+
<param name="name">The instrument name. cannot be <see langword="null" />.</param>
364+
<summary>Creates a Gauge instrument, which can be used to record non-additive values.</summary>
365365
<returns>To be added.</returns>
366-
<remarks>To be added.</remarks>
366+
<remarks>
367+
<para>Gauge is an Instrument which used to record non-additive values.</para>
368+
<para>Example uses for Gauge: record the room background noise level value when changes occur.</para>
369+
</remarks>
367370
</Docs>
368371
</Member>
369372
<Member MemberName="CreateGauge&lt;T&gt;">
@@ -423,13 +426,16 @@ Counter is an instrument that supports non-negative increments. Example uses for
423426
</Parameters>
424427
<Docs>
425428
<typeparam name="T">To be added.</typeparam>
426-
<param name="name">To be added.</param>
427-
<param name="unit">To be added.</param>
428-
<param name="description">To be added.</param>
429-
<param name="tags">To be added.</param>
430-
<summary>To be added.</summary>
429+
<param name="name">The instrument name. cannot be <see langword="null" />.</param>
430+
<param name="unit">Optional instrument unit of measurements.</param>
431+
<param name="description">Optional instrument description.</param>
432+
<param name="tags">tags to attach to the Gauge.</param>
433+
<summary>Create a metrics Gauge object.</summary>
431434
<returns>To be added.</returns>
432-
<remarks>To be added.</remarks>
435+
<remarks>
436+
<para>Gauge is an Instrument which used to record non-additive values.</para>
437+
<para>Example uses for Gauge: record the room background noise level value when changes occur.</para>
438+
</remarks>
433439
</Docs>
434440
</Member>
435441
<Member MemberName="CreateHistogram&lt;T&gt;">
@@ -480,10 +486,10 @@ Counter is an instrument that supports non-negative increments. Example uses for
480486
</Parameters>
481487
<Docs>
482488
<typeparam name="T">To be added.</typeparam>
483-
<param name="name">To be added.</param>
484-
<summary>To be added.</summary>
489+
<param name="name">The instrument name. Cannot be <see langword="null" />.</param>
490+
<summary>Histogram is an Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.</summary>
485491
<returns>To be added.</returns>
486-
<remarks>To be added.</remarks>
492+
<remarks>Example uses for Histogram: the request duration and the size of the response payload.</remarks>
487493
</Docs>
488494
</Member>
489495
<Member MemberName="CreateHistogram&lt;T&gt;">
@@ -688,14 +694,14 @@ Example uses for Histogram: The request duration and the size of the response pa
688694
</Parameters>
689695
<Docs>
690696
<typeparam name="T">To be added.</typeparam>
691-
<param name="name">To be added.</param>
692-
<param name="unit">To be added.</param>
693-
<param name="description">To be added.</param>
694-
<param name="tags">To be added.</param>
695-
<param name="advice">To be added.</param>
696-
<summary>To be added.</summary>
697+
<param name="name">The instrument name. Cannot be <see langword="null" />.</param>
698+
<param name="unit">Optional instrument unit of measurements.</param>
699+
<param name="description">Optional instrument description.</param>
700+
<param name="tags">Optional tags to attach to the histogram.</param>
701+
<param name="advice">Optional <see cref="T:System.Diagnostics.Metrics.InstrumentAdvice`1" /> to attach to the histogram.</param>
702+
<summary>Histogram is an Instrument which can be used to report arbitrary values that are likely to be statistically meaningful. It is intended for statistics such as histograms, summaries, and percentile.</summary>
697703
<returns>To be added.</returns>
698-
<remarks>To be added.</remarks>
704+
<remarks>Example uses for Histogram: the request duration and the size of the response payload.</remarks>
699705
</Docs>
700706
</Member>
701707
<Member MemberName="CreateObservableCounter&lt;T&gt;">

0 commit comments

Comments
 (0)