Add arguments to docs

[leonaves]

The documentation, while being very detailed, doesn't seem to actually mention what arguments a logger accepts. String? Object? Either? What about multiple parameters? What's the expected output when you send different parameters?

[kibertoad]

First of all, if you check documentation, e. g. the Creating your own Logger section, you would see that both string and object are supported. There are also plenty of examples in /examples section of the repo.
Second, if you believe that more explicit document would be helpful, PR is most welcome.

[leonaves]

I apologise, I'll try to be more civil; I've just been poring over these docs and am a little frustrated to find that an apparently widely used and popular library like this doesn't seem to actually specify how its used in its own docs. It seems this has caused issues in the past: #1427. In fact I was specifically looking for information on whether multiple parameters were supported due to some of the examples.

I would love to send a PR to add this information to the documentation, however I do not know what arguments the logger accepts myself, and so I cannot help to add this.

[leonaves]

I've edited the original comment to remove some of my clear frustration.

[kibertoad]

Thank you!
Plenty of stuff is supported, TBH, which is why documenting is tricky. Going through https://github.com/winstonjs/winston/tree/master/examples would be your best bet; and note that #1562 affects how errors are handled quite a bit.

[leonaves]

Problem with the examples is they don't show the output:

https://github.com/winstonjs/winston/blob/master/examples/custom-pretty-print.js#L17

Like here, how will this be logged?

[kibertoad]

I guess the only way to know is to try different combinations in IDE and document that.
And you are right, most likely one of the best ways to document would be to go through examples and augment them with what actually gets logged.

[indexzero]

Thanks for the feedback. Variable-arity is challenging to document without being overly verbose – hence why we've gone with examples. An assumption of a user was that they would actually run the examples (i.e. a hands-on approach).

Trying to consolidate the most common incantations into ./examples/quick-start.js. A PR to add the output to each of those statements would be welcome.