[
https://issues.apache.org/jira/browse/LOG4J2-2928?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Marcono1234 updated LOG4J2-2928:
--------------------------------
Description:
The documentation for the {{Logger}} and {{LogBuilder}} methods which create a
log message with parameters (e.g. {{Logger.error(message, p1, p2, ...)}}) 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)
# {{LogManager}} methods using the default {{MessageFactory}} should document
what the default is
----
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.
was:
The documentation for the {{Logger}} and {{LogBuilder}} methods which create a
log message with parameters (e.g. {{Logger.error(message, p1, p2, ...)}}) 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.
> 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
> Priority: Major
>
> The documentation for the {{Logger}} and {{LogBuilder}} methods which create
> a log message with parameters (e.g. {{Logger.error(message, p1, p2, ...)}})
> 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)
> # {{LogManager}} methods using the default {{MessageFactory}} should document
> what the default is
> ----
> 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)
