Skip to content

Commit e868509

Browse files
hdsdavidbarsky
hds
and
davidbarsky
committed
mock: document public APIs in span module (#2442)
This change adds documentation to the tracing-mock span module and all the public APIs within it. This includes doctests on all the methods which serve as examples. Additionally, the validation on `ExpectedSpan` was improved so that it validates the level and target during `enter` and `exit` as well as on `new_span`. The method `ExpectedSpan::with_field` was renamed to `with_fields` (plural) to match the same method on `ExpectedEvent` (and because multiple fields can be passed to it). A copy-paste typo was also fixed in the documentation for `ExpectedEvent::with_contextual_parent`. Refs: #539 Co-authored-by: David Barsky <[email protected]>
1 parent 00809ea commit e868509

File tree

15 files changed

+602
-83
lines changed

15 files changed

+602
-83
lines changed

‎tracing-attributes/tests/async_fn.rs‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -199,8 +199,8 @@ fn async_fn_with_async_trait() {
199199
let (subscriber, handle) = subscriber::mock()
200200
.new_span(
201201
span.clone()
202-
.with_field(expect::field("self"))
203-
.with_field(expect::field("v")),
202+
.with_fields(expect::field("self"))
203+
.with_fields(expect::field("v")),
204204
)
205205
.enter(span.clone())
206206
.new_span(span3.clone())
@@ -210,7 +210,7 @@ fn async_fn_with_async_trait() {
210210
.enter(span3.clone())
211211
.exit(span3.clone())
212212
.drop_span(span3)
213-
.new_span(span2.clone().with_field(expect::field("self")))
213+
.new_span(span2.clone().with_fields(expect::field("self")))
214214
.enter(span2.clone())
215215
.event(expect::event().with_fields(expect::field("val").with_value(&5u64)))
216216
.exit(span2.clone())
@@ -260,7 +260,7 @@ fn async_fn_with_async_trait_and_fields_expressions() {
260260
let span = expect::span().named("call");
261261
let (subscriber, handle) = subscriber::mock()
262262
.new_span(
263-
span.clone().with_field(
263+
span.clone().with_fields(
264264
expect::field("_v")
265265
.with_value(&5usize)
266266
.and(expect::field("test").with_value(&tracing::field::debug(10)))
@@ -330,21 +330,21 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
330330
let span4 = expect::span().named("sync_fun");
331331
let (subscriber, handle) = subscriber::mock()
332332
/*.new_span(span.clone()
333-
.with_field(
333+
.with_fields(
334334
expect::field("Self").with_value(&"TestImpler")))
335335
.enter(span.clone())
336336
.exit(span.clone())
337337
.drop_span(span)*/
338338
.new_span(
339339
span2
340340
.clone()
341-
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
341+
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
342342
)
343343
.enter(span2.clone())
344344
.new_span(
345345
span4
346346
.clone()
347-
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
347+
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
348348
)
349349
.enter(span4.clone())
350350
.exit(span4.clone())
@@ -357,7 +357,7 @@ fn async_fn_with_async_trait_and_fields_expressions_with_generic_parameter() {
357357
.new_span(
358358
span3
359359
.clone()
360-
.with_field(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
360+
.with_fields(expect::field("Self").with_value(&std::any::type_name::<TestImpl>())),
361361
)
362362
.enter(span3.clone())
363363
.exit(span3.clone())

‎tracing-attributes/tests/destructuring.rs‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ fn destructure_tuples() {
1111

1212
let (subscriber, handle) = subscriber::mock()
1313
.new_span(
14-
span.clone().with_field(
14+
span.clone().with_fields(
1515
expect::field("arg1")
1616
.with_value(&format_args!("1"))
1717
.and(expect::field("arg2").with_value(&format_args!("2")))
@@ -40,7 +40,7 @@ fn destructure_nested_tuples() {
4040

4141
let (subscriber, handle) = subscriber::mock()
4242
.new_span(
43-
span.clone().with_field(
43+
span.clone().with_fields(
4444
expect::field("arg1")
4545
.with_value(&format_args!("1"))
4646
.and(expect::field("arg2").with_value(&format_args!("2")))
@@ -72,7 +72,7 @@ fn destructure_refs() {
7272
let (subscriber, handle) = subscriber::mock()
7373
.new_span(
7474
span.clone()
75-
.with_field(expect::field("arg1").with_value(&1usize).only()),
75+
.with_fields(expect::field("arg1").with_value(&1usize).only()),
7676
)
7777
.enter(span.clone())
7878
.exit(span.clone())
@@ -98,7 +98,7 @@ fn destructure_tuple_structs() {
9898

9999
let (subscriber, handle) = subscriber::mock()
100100
.new_span(
101-
span.clone().with_field(
101+
span.clone().with_fields(
102102
expect::field("arg1")
103103
.with_value(&format_args!("1"))
104104
.and(expect::field("arg2").with_value(&format_args!("2")))
@@ -139,7 +139,7 @@ fn destructure_structs() {
139139

140140
let (subscriber, handle) = subscriber::mock()
141141
.new_span(
142-
span.clone().with_field(
142+
span.clone().with_fields(
143143
expect::field("arg1")
144144
.with_value(&format_args!("1"))
145145
.and(expect::field("arg2").with_value(&format_args!("2")))
@@ -184,7 +184,7 @@ fn destructure_everything() {
184184

185185
let (subscriber, handle) = subscriber::mock()
186186
.new_span(
187-
span.clone().with_field(
187+
span.clone().with_fields(
188188
expect::field("arg1")
189189
.with_value(&format_args!("1"))
190190
.and(expect::field("arg2").with_value(&format_args!("2")))

‎tracing-attributes/tests/err.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@ fn impl_trait_return_type() {
159159
let (subscriber, handle) = subscriber::mock()
160160
.new_span(
161161
span.clone()
162-
.with_field(expect::field("x").with_value(&10usize).only()),
162+
.with_fields(expect::field("x").with_value(&10usize).only()),
163163
)
164164
.enter(span.clone())
165165
.exit(span.clone())

‎tracing-attributes/tests/fields.rs‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ impl HasField {
4646

4747
#[test]
4848
fn fields() {
49-
let span = expect::span().with_field(
49+
let span = expect::span().with_fields(
5050
expect::field("foo")
5151
.with_value(&"bar")
5252
.and(expect::field("dsa").with_value(&true))
@@ -60,7 +60,7 @@ fn fields() {
6060

6161
#[test]
6262
fn expr_field() {
63-
let span = expect::span().with_field(
63+
let span = expect::span().with_fields(
6464
expect::field("s")
6565
.with_value(&"hello world")
6666
.and(expect::field("len").with_value(&"hello world".len()))
@@ -73,7 +73,7 @@ fn expr_field() {
7373

7474
#[test]
7575
fn two_expr_fields() {
76-
let span = expect::span().with_field(
76+
let span = expect::span().with_fields(
7777
expect::field("s")
7878
.with_value(&"hello world")
7979
.and(expect::field("s.len").with_value(&"hello world".len()))
@@ -87,7 +87,7 @@ fn two_expr_fields() {
8787

8888
#[test]
8989
fn clashy_expr_field() {
90-
let span = expect::span().with_field(
90+
let span = expect::span().with_fields(
9191
// Overriding the `s` field should record `s` as a `Display` value,
9292
// rather than as a `Debug` value.
9393
expect::field("s")
@@ -99,7 +99,7 @@ fn clashy_expr_field() {
9999
fn_clashy_expr_field("hello world");
100100
});
101101

102-
let span = expect::span().with_field(expect::field("s").with_value(&"s").only());
102+
let span = expect::span().with_fields(expect::field("s").with_value(&"s").only());
103103
run_test(span, || {
104104
fn_clashy_expr_field2("hello world");
105105
});
@@ -108,7 +108,7 @@ fn clashy_expr_field() {
108108
#[test]
109109
fn self_expr_field() {
110110
let span =
111-
expect::span().with_field(expect::field("my_field").with_value(&"hello world").only());
111+
expect::span().with_fields(expect::field("my_field").with_value(&"hello world").only());
112112
run_test(span, || {
113113
let has_field = HasField {
114114
my_field: "hello world",
@@ -119,7 +119,7 @@ fn self_expr_field() {
119119

120120
#[test]
121121
fn parameters_with_fields() {
122-
let span = expect::span().with_field(
122+
let span = expect::span().with_fields(
123123
expect::field("foo")
124124
.with_value(&"bar")
125125
.and(expect::field("param").with_value(&1u32))
@@ -132,15 +132,15 @@ fn parameters_with_fields() {
132132

133133
#[test]
134134
fn empty_field() {
135-
let span = expect::span().with_field(expect::field("foo").with_value(&"bar").only());
135+
let span = expect::span().with_fields(expect::field("foo").with_value(&"bar").only());
136136
run_test(span, || {
137137
fn_empty_field();
138138
});
139139
}
140140

141141
#[test]
142142
fn string_field() {
143-
let span = expect::span().with_field(expect::field("s").with_value(&"hello world").only());
143+
let span = expect::span().with_fields(expect::field("s").with_value(&"hello world").only());
144144
run_test(span, || {
145145
fn_string(String::from("hello world"));
146146
});

‎tracing-attributes/tests/instrument.rs‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ fn fields() {
6464
.with_target("my_target");
6565
let (subscriber, handle) = subscriber::mock()
6666
.new_span(
67-
span.clone().with_field(
67+
span.clone().with_fields(
6868
expect::field("arg1")
6969
.with_value(&2usize)
7070
.and(expect::field("arg2").with_value(&false))
@@ -76,7 +76,7 @@ fn fields() {
7676
.exit(span.clone())
7777
.drop_span(span)
7878
.new_span(
79-
span2.clone().with_field(
79+
span2.clone().with_fields(
8080
expect::field("arg1")
8181
.with_value(&3usize)
8282
.and(expect::field("arg2").with_value(&true))
@@ -126,15 +126,15 @@ fn skip() {
126126
let (subscriber, handle) = subscriber::mock()
127127
.new_span(
128128
span.clone()
129-
.with_field(expect::field("arg1").with_value(&2usize).only()),
129+
.with_fields(expect::field("arg1").with_value(&2usize).only()),
130130
)
131131
.enter(span.clone())
132132
.exit(span.clone())
133133
.drop_span(span)
134134
.new_span(
135135
span2
136136
.clone()
137-
.with_field(expect::field("arg1").with_value(&3usize).only()),
137+
.with_fields(expect::field("arg1").with_value(&3usize).only()),
138138
)
139139
.enter(span2.clone())
140140
.exit(span2.clone())
@@ -171,7 +171,7 @@ fn generics() {
171171

172172
let (subscriber, handle) = subscriber::mock()
173173
.new_span(
174-
span.clone().with_field(
174+
span.clone().with_fields(
175175
expect::field("arg1")
176176
.with_value(&format_args!("Foo"))
177177
.and(expect::field("arg2").with_value(&format_args!("false"))),
@@ -204,7 +204,7 @@ fn methods() {
204204

205205
let (subscriber, handle) = subscriber::mock()
206206
.new_span(
207-
span.clone().with_field(
207+
span.clone().with_fields(
208208
expect::field("self")
209209
.with_value(&format_args!("Foo"))
210210
.and(expect::field("arg1").with_value(&42usize)),
@@ -236,7 +236,7 @@ fn impl_trait_return_type() {
236236
let (subscriber, handle) = subscriber::mock()
237237
.new_span(
238238
span.clone()
239-
.with_field(expect::field("x").with_value(&10usize).only()),
239+
.with_fields(expect::field("x").with_value(&10usize).only()),
240240
)
241241
.enter(span.clone())
242242
.exit(span.clone())

‎tracing-mock/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ let span = expect::span().named("yak_shaving");
121121
let (subscriber, handle) = subscriber::mock()
122122
.new_span(
123123
span.clone()
124-
.with_field(expect::field("number_of_yaks").with_value(&yak_count).only()),
124+
.with_fields(expect::field("number_of_yaks").with_value(&yak_count).only()),
125125
)
126126
.enter(span.clone())
127127
.event(

‎tracing-mock/src/event.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -364,7 +364,7 @@ impl ExpectedEvent {
364364
///
365365
/// # Examples
366366
///
367-
/// The explicit parent is matched by name:
367+
/// The contextual parent is matched by name:
368368
///
369369
/// ```
370370
/// use tracing::subscriber::with_default;

‎tracing-mock/src/layer.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -431,7 +431,7 @@ impl MockLayerBuilder {
431431
/// let span = expect::span()
432432
/// .at_level(tracing::Level::INFO)
433433
/// .named("the span we're testing")
434-
/// .with_field(expect::field("testing").with_value(&"yes"));
434+
/// .with_fields(expect::field("testing").with_value(&"yes"));
435435
/// let (layer, handle) = layer::mock()
436436
/// .new_span(span)
437437
/// .run_with_handle();
@@ -455,7 +455,7 @@ impl MockLayerBuilder {
455455
/// let span = expect::span()
456456
/// .at_level(tracing::Level::INFO)
457457
/// .named("the span we're testing")
458-
/// .with_field(expect::field("testing").with_value(&"yes"));
458+
/// .with_fields(expect::field("testing").with_value(&"yes"));
459459
/// let (layer, handle) = layer::mock()
460460
/// .new_span(span)
461461
/// .run_with_handle();

0 commit comments

Comments
 (0)