[jira] [Created] (LOG4J2-2928) Improve documentation for log methods for messages with parameters

["Marcono1234 (Jira)" <ji...@apache.org>]

Marcono1234 created LOG4J2-2928:
-----------------------------------

             Summary: Improve documentation for log methods for messages with parameters
                 Key: LOG4J2-2928
                 URL: https://issues.apache.org/jira/browse/LOG4J2-2928
             Project: Log4j 2
          Issue Type: Improvement
          Components: Documentation
            Reporter: Marcono1234


The documentation for the {{Logger}} and {{LogBuilder}} methods which create a log message with parameters could probably be improved.

These methods currently only have their {{message}} method parameter documented as:
{quote}
the message to log; the format depends on the message factory.
{quote}
However, that is not very helpful because in the most common use case ({{LogManager.getLogger()}}) you are not even dealing with {{MessageFactory}} instances. So it is not clear what a "message factory" is or where to specify one; or even what the default one is.

I would therefore like to request the following changes:
# {{Logger}} and {{LogBuilder}} should have a section in their class documentation about messages with parameters, this section should explain:
#- Default message factory (i.e. used when {{LogManager.getLogger(...)}} method without {{MessageFactory}} is called); link to {{ParameterizedMessageFactory}} (which appears to be the default) and possibly additionally describe directly in {{Logger}} and {{LogManager}} doc its behavior:
#-- By default {{{}}} is used as placeholder
#-- Placeholders do not allow any further customization, most importantly they do not support the syntax of JDK's [{{MessageFormat}}|https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/MessageFormat.html] even though it looks similar
#-- If there are more arguments than placeholders and the last argument is a {{Throwable}} it is logged as such ({{ParameterizedMessageFactory}} doc currently does not mention that either!)
#- Link to {{LogManager}} methods allowing providing {{MessageFactory}} and link to {{getFormatterLogger(...)}} methods
#- Mention that alternatively log methods accepting {{Message}} can be used; link to [manual|https://logging.apache.org/log4j/2.x/manual/messages.html]
# All {{Logger}} and {{LogBuilder}} methods which create messages with parameters should link to these sections described in point 1 (HTML link)

----

Please let me know what you think about this. I will not create a pull request for this if that requires signing the Apache CLA.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)