defmt
defmt copied to clipboard
Documentation improvements
I'm coming back to using defmt/embedded after a relatively long break and am noticing some deficiencies in our docs, which I'll collect here.
-
#[global_logger]
docs should mention/link to the "pre-made" logger implementations - Proc macro docs are placed on their re-exports, which breaks them in rust-analyzer (r-a will only show them if they're on the proc macro fn)
-
Format
docs say that the "trait is used by the{:?}
format specifier", but it's used by any defmt macro, regardless of the format specifier - The
write!
macro link in theFormat
examples links tocore::write!
, notdefmt::write!
- Cargo features (
encoding-*
etc.) should be documented at the crate root, let's not make people locate theCargo.toml
to figure this out -
block
docs could be clearer. They contradict and say "Block until host has read all pending data" and also "might not succeed in flushing all pending data". They should clarify that whetherflush
will do anything at all is up to the logger in use, and logger crates should document whether they supportflush
. -
#[panic_handler]
docs don't say anything about how to use#[panic_handler]
, only link to the manual (which does explain it, but I think this belongs in the crate docs)
Thank you for the write-up. I think your last bullet point (panic_handler) misses the end of the sentence.