Extensions: Add doc comments to public APIs

[halter73]

This repo currently has a lot of public APIs without any doc comments.

There's already an issue (#610) about adding doc comments for EventId.

There's also a pretty old PR (#529) to add doc comments to console logger types. Having doc comments to indicate things like the default value of ConsoleLoggerOptions.IncludeScopes could certainly be useful. There are other console logging types that don't have doc comments like IConsoleLoggerSettings, but I haven't created an exhaustive list.

None of the (extension) methods on ILoggingBuilder (i.e. AddFilter, AddProvider, ClearProviders, SetMinimuLevel) have doc comments.

I Think it would be particularly useful to note in the SetMinimumLevel doc comments that the default LogLevel is Information meaning that Trace and Debug logs will be ignored. I think this should be noted on any API where a minimum level can be set.

[halter73]

I just learned that SetMinimumLoggingLevel gets overridden by what's configured in appsettings.json when using WebHost.CreateDefaultBuilder. I don't think this is obvious. While this is probably too detailed to go into a doc comment, I think this should be documented somewhere.

[nblumhardt]

Just came here after googling ILoggingBuilder SetMinimumLevel - is this ticket really the only place on the entire internet that this API is discussed? :-)

Confused about how the API is intended to work - https://github.com/datalust/seq-extensions-logging/issues/22#issuecomment-324170847 - some docs would be very useful.

[Triwaters]

@nblumhardt @halter73 As long as we're on the topic of scant documentation, have you ever tried to google this: iloggingbuilder.ClearProviders ?

No definition in sight that I can see (in terms of what it does) but ironically, it did take me here, of all places, for reasons only some combination of God and Google knows... Maybe because they know misery loves company?

[breyed]

There are many cases of non-obvious semantics with no documentation. For example, what does StringValues.Implicit(StringValues to String) return Count is 0?

If .NET's selling point is developer productivity, having to search out source code to determine behavior undermines the goal. Likewise, if long-term stability is a selling point, it's diminished too, since every use of the API is by definition undocumented behavior. Who can tell what is and is not intended to stay constant between versions?

[breyed]

I just noticed that the source has XML comments. However, they're not coming through to the API website or IntelliSense. Is the build pipeline broken?

[anurse]

These will be handled by the docs process in dotnet/runtime now, since the packages have moved there and the XML docs are handled in dotnet/dotnet-api-docs