Bug 1714578 - Pings testing api docs

[Dexterp37]

[docs only]

[brizental]

I noticed the submit section is lacking Java examples, would you mind filing a follow-up for that or just doing it in this PR?

On the examples you create this validatorRun boolean that is not really necessary it seems, or am I missing something? If not, can we remove that from the examples so as to not add more to it than necessary?

[Dexterp37]

On the examples you create this validatorRun boolean that is not really necessary it seems, or am I missing something? If not, can we remove that from the examples so as to not add more to it than necessary?

The boolean is used to make sure that the validator function actually runs. We have no other way to be completely sure of that in our APIs. We can't distinguish between "the callback run and detected no error" with the "callback did not run at all" (we do that in our tests, too)

[brizental]

The boolean is used to make sure that the validator function actually runs. We have no other way to be completely sure of that in our APIs. We can't distinguish between "the callback run and detected no error" with the "callback did not run at all" (we do that in our tests, too)

In this case, why does the Rust example not have that?

[brizental]

r+wc

[brizental]

IMHO, we could go further and maybe go through a real world case of ping testing in this page. It is kinda dry at the moment i.e. does not add too much to the docs. Good enough for this PR, but would you mind filing a follow-up bug?

[Dexterp37]

https://bugzilla.mozilla.org/show_bug.cgi?id=1716801

[badboy]

The boolean is used to make sure that the validator function actually runs. We have no other way to be completely sure of that in our APIs. We can't distinguish between "the callback run and detected no error" with the "callback did not run at all" (we do that in our tests, too)

In this case, why does the Rust example not have that?

Probably because it's so much more annoying to do in Rust:

let callback_was_called = Arc::new(AtomicBool::new(false));
let callback_was_called_2 = Arc::clone(&callback_was_called);

ping.test_before_next_submit(move |reason| {
    assert_eq!(None, reason);
    assert_eq!(1, metric.test_get_value(None).unwrap());
    callback_was_called_2.store(true, Ordering::SeqCst);
});

ping.submit(None);
assert!(callback_was_called.load(Ordering::SeqCst));

I'd say if you directly call ping.submit() in your test there's no need for callback_was_called (because users should trust us that we call it from submit).
It's only when you invoke submit behind the scenes and custom logic it might be a good idea I guess.