Doc: minitrace-attributes vs mintrace-macros
taqtiqa-mark opened this issue · 2 comments
I'm working on the #[trace] documentation for users.
From a (newish) user PoV: #[trace] is an attribute.
From a user perspective, especially users new to Rust, it adds complexity to be simultaneously encountering concepts of macros, proc-macros, attributes and proc-macro-attributes.
The use of proc-macros is an implementation detail that should not surface in the user documentation.
Renaming minitrace-macros to minitrace-attributes means the user docs can describe this attribute without having the usage instructions referring to minitrace-macros.
Another advantage is this frees minitrace-macros to hold macros, where the implementation could use macro-rules or pro-macros.
While I am opposed to replicating the log and tracing crate macros debug!(...), info!(...), etc. I'm beginning to think that there may be a use for record!(span, "key", "value") rather than span.record("key","value").
If that turns out to be the case it is conceivable users may want one of attributes or macros but not the other.
Using macro for proc_macro crate is a convention in Rust, i.e. https://crates.io/crates/tokio-macros. User experience is also essential. I suggest a solution that doesn't sacrifice any: add a Cargo feature attribute that reexports minitrace-macro for the user. And further, we can set the feature to default.
Closing this in favor of issue #140