[Issue 23323] New: std.logger (previously experimental) needs better documentation

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=23323

          Issue ID: 23323
           Summary: std.logger (previously experimental) needs better
                    documentation
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: phobos
          Assignee: nobody at puremagic.com
          Reporter: andrej.mitrovich at gmail.com

It took me quite a bit of time to realize why by default `log(string)` will do
nothing at all. In fact I think the default is very counter-intuitive.

Here's an example:

-----
import std.experimental.logger;

void main (){
    log("Hello?");
    logf(LogLevel.info, "%s", "test 1");
    logf(LogLevel.error, "%s", "test 2");
    log(LogLevel.info, "test 3");
}
-----

The first line will not be emitted to stdout or stderr, or anywhere for that
matter. The user is supposed to explicitly set the logging level. But it's not
even obvious for which logger they're supposed to do that.

The actual solution is:

-----
import std.experimental.logger;

void main (){
    stdThreadLocalLog().logLevel = LogLevel.info;
    log("Now this works");
}
-----

I lost a fair bit of time digging through phobos sources to understand what's
going on. I think we should at least document that you have to do this to get
any kind of output to stdout/stderr when calling 'log()'.

--