Tokio: trace-core: Pre-0.1 docs pass

[hawkw]

Subcrates

tokio-trace-core

Description

Prior to releasing tokio-trace-core 0.1 to crates.io, it would be nice to give the API docs a pass to make sure everything is explained clearly and the docs are accurate.

[hawkw]

I'm happy to _write_ any new documentation that's needed, but since I wrote the code, I'm having a hard time determining what needs to be explained better --- I don't have a good sense for what is and is not obvious.

It would be great to get feedback from anyone who's actually _used_ tokio-trace on what is unclear and needs to be explained better. @LucioFranco, @luser, and @jsgf, since all been trying out (or at least looking at) the trace APIs, I'd love to hear what you think needs to be better documented.

[LucioFranco]

The docs for Subscriber::enabled should mention that it only gets called if the corresponding register_callsite call returns Interest::sometimes. I would also like to see a bit more on the life cycle of the subscriber as it is a bit unclear currently.

[hawkw]

@LucioFranco what do you mean exactly by "the life cycle of the subscriber"?

[LucioFranco]

@hawkw more so around, when does enabled get called etc.

[luser]

These docs look pretty great for a 0.1! You explain all the major concepts and how they fit together and have useful examples. At some point I can see it being useful to have a separate section for "migrating existing code from log / env_logger", since those crates are pretty pervasive and mapping between the two can be a little difficult conceptually.

I think it'd be nice to mention tokio-trace-futures in the section about Spans. It would also be worthwhile to explicitly call out tokio-trace-fmt in the "In executables" paragraph as a way to roughly achieve parity for projects that are already using log + env_logger. I believe you also mentioned tokio-trace-log as a way to capture unstructured log messages from other crates which was one of the first things I asked about.