defmt icon indicating copy to clipboard operation
defmt copied to clipboard

Documentation improvements

Open jonas-schievink opened this issue 2 years ago • 1 comments

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 the Format examples links to core::write!, not defmt::write!
  • Cargo features (encoding-* etc.) should be documented at the crate root, let's not make people locate the Cargo.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 whether flush will do anything at all is up to the logger in use, and logger crates should document whether they support flush.
  • #[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)

jonas-schievink avatar May 25 '22 13:05 jonas-schievink

Thank you for the write-up. I think your last bullet point (panic_handler) misses the end of the sentence.

Urhengulas avatar May 31 '22 11:05 Urhengulas