[GitHub] [logging-log4cxx] fulldecent commented on pull request #84: Fix underspecification for logger

[GitBox <gi...@apache.org>]

fulldecent commented on pull request #84:
URL: https://github.com/apache/logging-log4cxx/pull/84#issuecomment-994867538


   Coming back here with more time to type.
   
   This issue discussed here affects:
   
   - The Apache Log4j 2 API specification
   - Every Apache Log4j 2 implementation
   
   The distinction between these two things is discussed at: "API Separation" in https://logging.apache.org/log4j/2.x/
   
   ---
   
   # Here is the problem:
   
   On the marketing page https://logging.apache.org/log4j/2.x/ it is stated:
   
   > The Log4j API supports logging Messages instead of just Strings
   
   This is a normative statement which significantly describes methods in log4cxx and every other implementation.
   
   That means that any API documentation and implementation of Log4j 2 (including log4cxx) is expected to support "Messages".
   
   The documentation in the line referenced in this PR (as well as all other logging methods in this implementation, all other logging methods in all other implementations, and in the specification itself) MUST (meaning defined in RFC 2119) support Messages.
   
   The above-referenced API documentation mentions only "messages".
   
   What is the difference between a "message" and a "Message"? Well the lowercase version has the plain English meaning of approximately "something which is said". And the uppercase version has a meaning specified at https://logging.apache.org/log4j/2.x/manual/messages.html
   
   # Required fix for API conformance
   
   To be compliant with normative references in the authoritative API specifications, the above-cited function must expanded to support Messages, not just strings.
   
   That includes updating the specification (function documentation), and possibly the implementation. If this implementation does not support Messages, then it is not fully conformant with the API specification and such deficiency should be specifically noted.
   
   # Recommended fix for safety
   
   In addition to the minimal change of making one of the letters uppercase, it can be very helpful to provide context and related useful documentation for what Messages means.
   
   That could include linking to the normative page at https://logging.apache.org/log4j/2.x/manual/messages.html or possibly more context-specification (i.e. related only to this implementation) details on what messages are supported.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@logging.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org