Crate evaluation for 2017-05-16: log

libs
37

Updated the op with the following for documentation:

Crate issues

  • Document what happens when log is initialized more than once
    • crate docs say “may only be initalized once”, not why, or what happens if you initialize twice
  • Use env_logger instead of my_logger in example
    • env_logger is something a user can try themselves
  • Crate docs should mention the logging levels and corresponding macros
  • Add example for log! macro
    • using both variants
  • Document max_level_*, release_max_level_* features in crate docs
  • Add examples to debug!, error!, info!, trace!, warn!
    • Both pattern variants
  • Expand log! docs for max_level_*
    • Seems like a non-sequiter here, but other logging macros have better explanations of this feature
  • Add example for second log_enabled! pattern variant
    • There’s an example, but it only covers one variant of the macro
  • LogLocation doc improvements
    • How are these values created?
    • Are these for logger implementors or log user?
    • Add an example
  • LogMetadata doc improvements
    • How are these values created?
    • Are these for logger implementors or log user?
    • Add an example
  • LogRecord doc improvements
    • How are these values created?
    • Are these for logger implementors or log user?
    • What’s the difference between the ‘level’/‘target’ accessors here and on the attached LogMetadata?
    • Add an example
  • SetLoggerError doc improvements
    • Add links to functions
  • ShutdownLeggerError doc improvements
    • Add links to functions
  • LogLevel doc improvements
    • Do end-users use this type or just loggers?
    • Add link to LogLevelFilter
  • LogLevelFilter doc improvements
    • Do end-users use this type or just loggers?
    • Add link to LogLevel
  • max_log_level
    • Add links
  • set_logger docs
    • Add links
    • Add “Errors” section
    • Add example
  • set_logger_raw docs
    • Add links
    • Add “Errors” section
    • Add example
  • shutdown_logger docs
    • Add links
    • Add “Errors” section
    • Add example
  • shutdown_logger_raw docs
    • Add links
    • Add “Errors” section
    • Add example
  • Add links to crate docs
  • Add CI badges to Cargo.toml
  • Change Cargo.toml ocumentation key to point to https://docs.rs/log
  • Add keywords to Cargo.toml
  • Change html_root_url to https://docs.rs/$crate/$version

Guidelines changes

Discussion topics

  • Are there any panic conditions in this lib? Not documented.
  • There are several “musts” about usage here that are kinda scary
    • should we say more about why?
    • e.g. “This function may only be called once in the lifetime of a program, and may not be called before set_logger”
      • This is a safe function and I sure can do what is says I can’t
3 Likes