You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@logging.apache.org by sw...@apache.org on 2022/12/17 23:38:18 UTC
[logging-log4cxx] branch next_stable updated: Improve web-site documentation (#161)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch next_stable
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
The following commit(s) were added to refs/heads/next_stable by this push:
new 0aa1f619 Improve web-site documentation (#161)
0aa1f619 is described below
commit 0aa1f61921ebf204dd3e0eadc8feb8fca69c0e66
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Sun Dec 18 10:38:13 2022 +1100
Improve web-site documentation (#161)
* Restructure usage documentation. Prevent most doxygen warnings
* Correct blatently erroneous comments. De-duplicate 'Performance' document heading
* Use 'com::foo' as the example namespace instead of 'UserLib'
---
src/examples/cpp/CMakeLists.txt | 6 +-
src/examples/cpp/MyApp.properties | 4 +-
src/examples/cpp/UserLib/logmanager.h | 9 -
src/examples/cpp/auto-configured.cpp | 4 +-
src/examples/cpp/com/foo/config.h | 6 +
.../logmanager.cpp => com/foo/config3.cpp} | 11 +-
src/main/cpp/propertyconfigurator.cpp | 2 +-
src/main/include/log4cxx/appenderskeleton.h | 2 +-
src/main/include/log4cxx/defaultconfigurator.h | 2 +-
src/main/include/log4cxx/filter/levelmatchfilter.h | 23 +-
src/main/include/log4cxx/filter/levelrangefilter.h | 33 ++-
.../include/log4cxx/filter/loggermatchfilter.h | 24 +-
src/main/include/log4cxx/helpers/loglog.h | 40 ++--
src/main/include/log4cxx/helpers/optionconverter.h | 12 +-
src/main/include/log4cxx/helpers/systemerrwriter.h | 2 +-
src/main/include/log4cxx/helpers/systemoutwriter.h | 2 +-
src/main/include/log4cxx/hierarchy.h | 2 +-
src/main/include/log4cxx/layout.h | 4 +-
src/main/include/log4cxx/logger.h | 50 ++--
src/main/include/log4cxx/logmanager.h | 15 +-
src/main/include/log4cxx/net/smtpappender.h | 4 +-
src/main/include/log4cxx/net/xmlsocketappender.h | 14 +-
.../log4cxx/pattern/classnamepatternconverter.h | 1 -
.../log4cxx/pattern/propertiespatternconverter.h | 6 +-
src/main/include/log4cxx/patternlayout.h | 9 +-
src/main/include/log4cxx/propertyconfigurator.h | 23 +-
src/main/include/log4cxx/spi/filter.h | 3 +-
src/main/include/log4cxx/spi/loggerrepository.h | 7 +-
src/main/include/log4cxx/spi/optionhandler.h | 8 +-
src/site/doxy/Doxyfile.in | 30 ---
src/site/markdown/change-report-gh.md | 88 +++----
src/site/markdown/development/build-cmake.md | 24 +-
src/site/markdown/usage.md | 261 ++++++++++-----------
33 files changed, 343 insertions(+), 388 deletions(-)
diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt
index 0f6d0dab..afd396cd 100644
--- a/src/examples/cpp/CMakeLists.txt
+++ b/src/examples/cpp/CMakeLists.txt
@@ -30,12 +30,12 @@ endif()
foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES)
add_executable(${exampleName} ${exampleName}.cpp)
- if(${exampleName} STREQUAL auto-configured)
- target_sources(${exampleName} PRIVATE UserLib/logmanager.cpp)
- endif()
if(${exampleName} STREQUAL MyApp2)
target_sources(${exampleName} PRIVATE com/foo/config2.cpp com/foo/bar.cpp)
endif()
+ if(${exampleName} STREQUAL auto-configured)
+ target_sources(${exampleName} PRIVATE com/foo/config3.cpp )
+ endif()
target_compile_definitions(${exampleName} PRIVATE ${EXAMPLE_COMPILE_DEFINITIONS} ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
target_include_directories(${exampleName} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
target_link_libraries(${exampleName} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${EXPAT_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS})
diff --git a/src/examples/cpp/MyApp.properties b/src/examples/cpp/MyApp.properties
index 386d5051..da4840cd 100644
--- a/src/examples/cpp/MyApp.properties
+++ b/src/examples/cpp/MyApp.properties
@@ -1,4 +1,5 @@
-log4j.rootLogger=debug, stdout, R
+# Append log events onto stdout and R
+log4j.rootLogger=DEBUG, stdout, R
log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
@@ -9,6 +10,7 @@ log4j.appender.stdout.layout.ConversionPattern=%5p [%t] (%f:%L) - %m%n
log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=example.log
+# Move example.log to example.log.1 at 100 KB in size
log4j.appender.R.MaxFileSize=100KB
# Keep one backup file
log4j.appender.R.MaxBackupIndex=1
diff --git a/src/examples/cpp/UserLib/logmanager.h b/src/examples/cpp/UserLib/logmanager.h
deleted file mode 100644
index 31274093..00000000
--- a/src/examples/cpp/UserLib/logmanager.h
+++ /dev/null
@@ -1,9 +0,0 @@
-#include <log4cxx/logger.h>
-
-namespace UserLib
-{
-
- extern auto
-getLogger(const std::string& name = std::string()) -> log4cxx::LoggerPtr;
-
-} // namespace UserLib
diff --git a/src/examples/cpp/auto-configured.cpp b/src/examples/cpp/auto-configured.cpp
index b5c42e3b..fb0a9a5d 100644
--- a/src/examples/cpp/auto-configured.cpp
+++ b/src/examples/cpp/auto-configured.cpp
@@ -14,9 +14,9 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-#include "UserLib/logmanager.h"
+#include "com/foo/config.h"
-extern auto rootLogger = UserLib::getLogger();
+extern auto rootLogger = com::foo::getLogger();
static struct ExampleStaticData {
ExampleStaticData() {
diff --git a/src/examples/cpp/com/foo/config.h b/src/examples/cpp/com/foo/config.h
index 02155999..a690c4b4 100644
--- a/src/examples/cpp/com/foo/config.h
+++ b/src/examples/cpp/com/foo/config.h
@@ -1,9 +1,15 @@
#ifndef COM_FOO_CONFIG_H_
#define COM_FOO_CONFIG_H_
#include <log4cxx/logger.h>
+
+/// Types specific to foo.com
namespace com { namespace foo {
+/// The logger pointer we use
using LoggerPtr = log4cxx::LoggerPtr;
+
+/// Retrieve the \c name logger pointer.
+/// Configure Log4cxx on the first call.
extern auto getLogger(const std::string& name = std::string()) -> LoggerPtr;
} } // namespace com::foo
diff --git a/src/examples/cpp/UserLib/logmanager.cpp b/src/examples/cpp/com/foo/config3.cpp
similarity index 95%
rename from src/examples/cpp/UserLib/logmanager.cpp
rename to src/examples/cpp/com/foo/config3.cpp
index d56cd4ea..d38ae43c 100644
--- a/src/examples/cpp/UserLib/logmanager.cpp
+++ b/src/examples/cpp/com/foo/config3.cpp
@@ -14,12 +14,11 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-#include <UserLib/logmanager.h>
+#include "config.h"
#include <log4cxx/logmanager.h>
#include <log4cxx/logstring.h>
#include <log4cxx/defaultconfigurator.h>
#include <log4cxx/helpers/pool.h>
-#include <log4cxx/spi/loggerrepository.h>
#include <log4cxx/file.h>
#include <log4cxx/helpers/loglog.h>
#include <log4cxx/helpers/transcoder.h>
@@ -143,11 +142,11 @@ void SelectConfigurationFile() {
} // namespace
-namespace UserLib {
+namespace com { namespace foo {
-// Retrieve the \c name logger.
+// Retrieve the \c name logger pointer.
// Configure Log4cxx on the first call.
-auto getLogger(const std::string& name) -> log4cxx::LoggerPtr {
+auto getLogger(const std::string& name) -> LoggerPtr {
static struct log4cxx_initializer {
log4cxx_initializer() {
SelectConfigurationFile();
@@ -161,4 +160,4 @@ auto getLogger(const std::string& name) -> log4cxx::LoggerPtr {
: log4cxx::LogManager::getLogger(name);
}
-} // namespace UserLib
+} } // namespace com::foo
diff --git a/src/main/cpp/propertyconfigurator.cpp b/src/main/cpp/propertyconfigurator.cpp
index 221674a6..ea5c340a 100644
--- a/src/main/cpp/propertyconfigurator.cpp
+++ b/src/main/cpp/propertyconfigurator.cpp
@@ -441,7 +441,7 @@ AppenderPtr PropertyConfigurator::parseAppender(
props, prefix, Appender::getStaticClass(), 0);
appender = log4cxx::cast<Appender>( obj );
- // Map obsolete DailyRollingFileAppender propertiy configuration
+ // Map obsolete DailyRollingFileAppender property configuration
if (!appender &&
StringHelper::endsWith(OptionConverter::findAndSubst(prefix, props), LOG4CXX_STR("DailyRollingFileAppender")))
{
diff --git a/src/main/include/log4cxx/appenderskeleton.h b/src/main/include/log4cxx/appenderskeleton.h
index b04c2c05..f91545e2 100644
--- a/src/main/include/log4cxx/appenderskeleton.h
+++ b/src/main/include/log4cxx/appenderskeleton.h
@@ -146,7 +146,7 @@ class LOG4CXX_EXPORT AppenderSkeleton :
/**
Set the layout for this appender. Note that some appenders have
their own (fixed) layouts or do not use one. For example, the
- {@link net::SocketAppender SocketAppender} ignores the layout set
+ {@link net::XMLSocketAppender XMLSocketAppender} ignores the layout set
here.
*/
void setLayout(const LayoutPtr layout1) override;
diff --git a/src/main/include/log4cxx/defaultconfigurator.h b/src/main/include/log4cxx/defaultconfigurator.h
index 0825f2d7..59561274 100644
--- a/src/main/include/log4cxx/defaultconfigurator.h
+++ b/src/main/include/log4cxx/defaultconfigurator.h
@@ -56,7 +56,7 @@ class LOG4CXX_EXPORT DefaultConfigurator
or the environment variables "LOG4CXX_CONFIGURATION_WATCH_SECONDS" contains a positive number
a background thread is started that will periodically check for a change to the configuration file
and apply any configuration changes found.
- .*/
+ */
static void configure(spi::LoggerRepositoryPtr repository);
/**
diff --git a/src/main/include/log4cxx/filter/levelmatchfilter.h b/src/main/include/log4cxx/filter/levelmatchfilter.h
index 8776af96..5221e210 100644
--- a/src/main/include/log4cxx/filter/levelmatchfilter.h
+++ b/src/main/include/log4cxx/filter/levelmatchfilter.h
@@ -30,16 +30,15 @@ namespace filter
/**
This is a very simple filter based on level matching.
-<p>The filter admits two options <b>LevelToMatch</b> and
-<b>AcceptOnMatch</b>. If there is an exact match between the value
-of the <b>LevelToMatch</b> option and the level of the {@link
-spi::LoggingEvent LoggingEvent}, then the #decide method returns {@link
-spi::Filter#ACCEPT ACCEPT} in case the <b>AcceptOnMatch</b>
-option value is set to <code>true</code>, if it is <code>false</code>
-then {@link spi::Filter#DENY DENY} is returned. If there is no match,
-{@link spi::Filter#NEUTRAL NEUTRAL} is returned.
+<p>The filter admits two options <code>levelToMatch</code> and
+<code>acceptOnMatch</code>. If there is an exact match between the value
+of the <code>levelToMatch</code> option and the level of the
+{@link spi::LoggingEvent LoggingEvent}, then the #decide method returns
+{@link spi::Filter::ACCEPT ACCEPT} in case the <code>acceptOnMatch</code>
+option value is set to <code>true</code>,
+if it is <code>false</code> then {@link spi::Filter::DENY DENY} is returned.
+If there is no match, {@link spi::Filter::NEUTRAL NEUTRAL} is returned.
*/
-
class LOG4CXX_EXPORT LevelMatchFilter : public spi::Filter
{
private:
@@ -73,12 +72,12 @@ class LOG4CXX_EXPORT LevelMatchFilter : public spi::Filter
Return the decision of this filter.
Returns {@link spi::Filter#NEUTRAL NEUTRAL} if the
- <b>LevelToMatch</b> option is not set or if there is not match.
+ <code>levelToMatch</code> option is not set or if there is not match.
Otherwise, if there is a match, then the returned decision is
- {@link spi::Filter#ACCEPT ACCEPT} if the <b>AcceptOnMatch</b>
+ {@link spi::Filter#ACCEPT ACCEPT} if the <code>acceptOnMatch</code>
property is set to <code>true</code>. The returned decision is
{@link spi::Filter#DENY DENY} if the
- <b>AcceptOnMatch</b> property is set to false.
+ <code>acceptOnMatch</code> property is set to false.
*/
FilterDecision decide(const spi::LoggingEventPtr& event) const override;
}; // class LevelMatchFilter
diff --git a/src/main/include/log4cxx/filter/levelrangefilter.h b/src/main/include/log4cxx/filter/levelrangefilter.h
index 8a69b983..d37c04f0 100644
--- a/src/main/include/log4cxx/filter/levelrangefilter.h
+++ b/src/main/include/log4cxx/filter/levelrangefilter.h
@@ -29,26 +29,25 @@ namespace filter
This is a very simple filter based on level matching, which can be
used to reject messages with priorities outside a certain range.
-<p>The filter admits three options <b>LevelMin</b>, <b>LevelMax</b>
-and <b>AcceptOnMatch</b>.
+<p>The filter admits three options <code>levelMin</code>, <code>levelMax</code>
+and <code>acceptOnMatch</code>.
<p>If the level of the {@link spi::LoggingEvent LoggingEvent} is not
between Min and Max (inclusive), then {@link spi::Filter#DENY DENY}
is returned.
<p> If the Logging event level is within the specified range, then if
-<b>AcceptOnMatch</b> is true, {@link spi::Filter#ACCEPT ACCEPT} is
-returned, and if <b>AcceptOnMatch</b> is false,
+<code>acceptOnMatch</code> is true, {@link spi::Filter#ACCEPT ACCEPT} is
+returned, and if <code>acceptOnMatch</code> is false,
{@link spi::Filter#NEUTRAL NEUTRAL} is returned.
-<p>If <code>LevelMin</code>w is not defined, then there is no
+<p>If <code>levelMin</code>w is not defined, then there is no
minimum acceptable level (ie a level is never rejected for
-being too "low"/unimportant). If <code>LevelMax</code> is not
+being too "low"/unimportant). If <code>levelMax</code> is not
defined, then there is no maximum acceptable level (ie a
level is never rejected for beeing too "high"/important).
-<p>Refer to the {@link
-AppenderSkeleton#setThreshold setThreshold} method
+<p>Refer to the {@link AppenderSkeleton#setThreshold setThreshold} method
available to <code>all</code> appenders extending
AppenderSkeleton for a more convenient way to
filter out events by level.
@@ -76,32 +75,32 @@ class LOG4CXX_EXPORT LevelRangeFilter : public spi::Filter
void setOption(const LogString& option, const LogString& value) override;
/**
- Set the <code>LevelMin</code> option.
+ Set the <code>levelMin</code> option.
*/
void setLevelMin(const LevelPtr& levelMin1);
/**
- Get the value of the <code>LevelMin</code> option.
+ Get the value of the <code>levelMin</code> option.
*/
const LevelPtr& getLevelMin() const;
/**
- Set the <code>LevelMax</code> option.
+ Set the <code>levelMax</code> option.
*/
void setLevelMax(const LevelPtr& levelMax1);
/**
- Get the value of the <code>LevelMax</code> option.
+ Get the value of the <code>levelMax</code> option.
*/
const LevelPtr& getLevelMax() const;
/**
- Set the <code>AcceptOnMatch</code> option.
+ Set the <code>acceptOnMatch</code> option.
*/
void setAcceptOnMatch(bool acceptOnMatch1);
/**
- Get the value of the <code>AcceptOnMatch</code> option.
+ Get the value of the <code>acceptOnMatch</code> option.
*/
bool getAcceptOnMatch() const;
@@ -109,12 +108,12 @@ class LOG4CXX_EXPORT LevelRangeFilter : public spi::Filter
Return the decision of this filter.
Returns {@link spi::Filter#NEUTRAL NEUTRAL} if the
- <b>LevelToMatch</b> option is not set or if there is not match.
+ <code>levelToMatch</code> option is not set or if there is not match.
Otherwise, if there is a match, then the returned decision is
{@link spi::Filter#ACCEPT ACCEPT} if the
- <b>AcceptOnMatch</b> property is set to <code>true</code>. The
+ <code>acceptOnMatch</code> property is set to <code>true</code>. The
returned decision is {@link spi::Filter#DENY DENY} if the
- <b>AcceptOnMatch</b> property is set to false.
+ <code>acceptOnMatch</code> property is set to false.
*/
FilterDecision decide(const spi::LoggingEventPtr& event) const override;
}; // class LevelRangeFilter
diff --git a/src/main/include/log4cxx/filter/loggermatchfilter.h b/src/main/include/log4cxx/filter/loggermatchfilter.h
index 679f639e..e820ee97 100644
--- a/src/main/include/log4cxx/filter/loggermatchfilter.h
+++ b/src/main/include/log4cxx/filter/loggermatchfilter.h
@@ -30,15 +30,15 @@ namespace filter
/**
This is a very simple filter based on logger name matching.
- <p>The filter admits two options <b>LoggerToMatch</b> and
- <b>AcceptOnMatch</b>. If there is an exact match between the value
- of the <b>LoggerToMatch</b> option and the logger of the {@link
- spi::LoggingEvent LoggingEvent}, then the #decide method returns {@link
- spi::Filter#ACCEPT ACCEPT} in case the <b>AcceptOnMatch</b> option value is set
- to <code>true</code>, if it is <code>false</code> then {@link
- spi::Filter#DENY} is returned. If there is no match, {@link
- spi::Filter#NEUTRAL} is returned. A loggerToMatch of "root"
- matches both the root logger and a logger named "root".
+ <p>The filter admits two options <code>loggerToMatch</code> and
+ <code>acceptOnMatch</code>. If there is an exact match between the value
+ of the <code>loggerToMatch</code> option and the logger of the
+ {@link spi::LoggingEvent LoggingEvent}, then the #decide method returns
+ {@link spi::Filter#ACCEPT ACCEPT} in case the <code>acceptOnMatch</code> option value is set
+ to <code>true</code>, if it is <code>false</code> then
+ {@link spi::Filter#DENY} is returned. If there is no match,
+ {@link spi::Filter#NEUTRAL} is returned.
+ A loggerToMatch of "root" matches both the root logger and a logger named "root".
*/
@@ -75,12 +75,12 @@ class LOG4CXX_EXPORT LoggerMatchFilter : public spi::Filter
Return the decision of this filter.
Returns {@link spi::Filter#NEUTRAL NEUTRAL} if the
- <b>LoggerToMatch</b> option is not set or if there is not match.
+ <code>loggerToMatch</code> option is not set or if there is not match.
Otherwise, if there is a match, then the returned decision is
- {@link spi::Filter#ACCEPT ACCEPT} if the <b>AcceptOnMatch</b>
+ {@link spi::Filter#ACCEPT ACCEPT} if the <code>acceptOnMatch</code>
property is set to <code>true</code>. The returned decision is
{@link spi::Filter#DENY DENY} if the
- <b>AcceptOnMatch</b> property is set to false.
+ <code>acceptOnMatch</code> property is set to false.
*/
FilterDecision decide(const spi::LoggingEventPtr& event) const override;
}; // class LoggerMatchFilter
diff --git a/src/main/include/log4cxx/helpers/loglog.h b/src/main/include/log4cxx/helpers/loglog.h
index 43165066..10f65077 100644
--- a/src/main/include/log4cxx/helpers/loglog.h
+++ b/src/main/include/log4cxx/helpers/loglog.h
@@ -31,13 +31,11 @@ This class used to output log statements from within the log4cxx package.
<p>Log4cxx components cannot make log4cxx logging calls. However, it is
sometimes useful for the user to learn about what log4cxx is
-doing. You can enable log4cxx internal logging by calling the
+doing. You can enable log4cxx internal debug logging by calling the
<b>#setInternalDebugging</b> method.
-<p>All log4cxx internal debug calls go to standard output
-where as internal error messages are sent to
-standard error output. All internal messages are prepended with
-the string "log4cxx: ".
+<p>All LogLog messages are written to SystemErrWriter
+prepended with the string "log4cxx: ".
*/
class LOG4CXX_EXPORT LogLog
{
@@ -53,42 +51,48 @@ class LOG4CXX_EXPORT LogLog
~LogLog();
/**
- Allows to enable/disable log4cxx internal logging.
+ Use the value of \c enabled as the new internal debug logging state.
*/
static void setInternalDebugging(bool enabled);
/**
- This method is used to output log4cxx internal debug
- statements. Output goes to the standard output.
+ Output \c msg to SystemErrWriter if internal debug logging is enabled.
*/
static void debug(const LogString& msg);
+ /**
+ Output \c msg and <code>ex.what()</code> to SystemErrWriter if internal debug logging is enabled.
+ */
static void debug(const LogString& msg, const std::exception& e);
/**
- This method is used to output log4cxx internal error
- statements. There is no way to disable error statements.
- Output goes to stderr.
+ Output \c msg to SystemErrWriter unconditionally.
*/
static void error(const LogString& msg);
- static void error(const LogString& msg, const std::exception& e);
+ /**
+ Output \c msg and <code>ex.what()</code> to SystemErrWriter unconditionally.
+ */
+ static void error(const LogString& msg, const std::exception& ex);
/**
+ Change quiet mode to \c newValue.
+
In quiet mode LogLog generates strictly no output, not even
for errors.
- @param quietMode <code>true</code> for no output.
+ @param newValue <code>true</code> for no output.
*/
- static void setQuietMode(bool quietMode);
+ static void setQuietMode(bool newValue);
/**
- This method is used to output log4cxx internal warning
- statements. There is no way to disable warning statements.
- Output goes to stderr.
+ Output \c msg to SystemErrWriter unconditionally.
*/
static void warn(const LogString& msg);
- static void warn(const LogString& msg, const std::exception& e);
+ /**
+ Output \c msg and <code>ex.what()</code> to SystemErrWriter unconditionally.
+ */
+ static void warn(const LogString& msg, const std::exception& ex);
private:
static void emit(const LogString& msg);
diff --git a/src/main/include/log4cxx/helpers/optionconverter.h b/src/main/include/log4cxx/helpers/optionconverter.h
index 4b20ac65..6edab8ee 100644
--- a/src/main/include/log4cxx/helpers/optionconverter.h
+++ b/src/main/include/log4cxx/helpers/optionconverter.h
@@ -81,9 +81,9 @@ class LOG4CXX_EXPORT OptionConverter
<p>For example, if the System properties contains "key=value", then
the call
- <pre>
- String s = OptionConverter.substituteVars("Value of key is ${key}.");
- </pre>
+ ~~~{.cpp}
+ auto s = OptionConverter.substituteVars("Value of key is ${key}.");
+ ~~~
will set the variable <code>s</code> to "Value of key is value.".
@@ -94,9 +94,9 @@ class LOG4CXX_EXPORT OptionConverter
<p>For example, if system propeties contains no value for the key
"inexistentKey", then the call
- <pre>
- String s = OptionConverter.subsVars("Value of inexistentKey is [${inexistentKey}]");
- </pre>
+ ~~~{.cpp}
+ auto s = OptionConverter.subsVars("Value of inexistentKey is [${inexistentKey}]");
+ ~~~
will set <code>s</code> to "Value of inexistentKey is []"
<p>An IllegalArgumentException is thrown if
diff --git a/src/main/include/log4cxx/helpers/systemerrwriter.h b/src/main/include/log4cxx/helpers/systemerrwriter.h
index 26304335..a4ffdc1d 100644
--- a/src/main/include/log4cxx/helpers/systemerrwriter.h
+++ b/src/main/include/log4cxx/helpers/systemerrwriter.h
@@ -26,7 +26,7 @@ namespace helpers
{
/**
-* Abstract class for writing to character streams.
+* Sends output to <code>stderr</code>.
*/
class LOG4CXX_EXPORT SystemErrWriter : public Writer
{
diff --git a/src/main/include/log4cxx/helpers/systemoutwriter.h b/src/main/include/log4cxx/helpers/systemoutwriter.h
index 9b3d207e..81b70c7f 100644
--- a/src/main/include/log4cxx/helpers/systemoutwriter.h
+++ b/src/main/include/log4cxx/helpers/systemoutwriter.h
@@ -26,7 +26,7 @@ namespace helpers
{
/**
-* Abstract class for writing to character streams.
+* Sends output to <code>stdout</code>.
*/
class LOG4CXX_EXPORT SystemOutWriter : public Writer
{
diff --git a/src/main/include/log4cxx/hierarchy.h b/src/main/include/log4cxx/hierarchy.h
index bb3a692d..1173a14f 100644
--- a/src/main/include/log4cxx/hierarchy.h
+++ b/src/main/include/log4cxx/hierarchy.h
@@ -196,7 +196,7 @@ class LOG4CXX_EXPORT Hierarchy : public spi::LoggerRepository
Shutting down a hierarchy will <em>safely</em> close and remove
all appenders in all categories including the root logger.
- <p>Some appenders such as {@link net::SocketAppender SocketAppender}
+ <p>Some appenders such as {@link net::XMLSocketAppender XMLSocketAppender}
and AsyncAppender need to be closed before the
application exists. Otherwise, pending logging events might be
lost.
diff --git a/src/main/include/log4cxx/layout.h b/src/main/include/log4cxx/layout.h
index 3922e48a..621b17db 100644
--- a/src/main/include/log4cxx/layout.h
+++ b/src/main/include/log4cxx/layout.h
@@ -72,8 +72,8 @@ class LOG4CXX_EXPORT Layout :
object, then the layout should return <code>true</code>.
<p>The SimpleLayout, TTCCLayout,
- PatternLayout all return <code>true</code>. The {@link
- xml::XMLLayout XMLLayout} returns <code>false</code>.
+ PatternLayout all return <code>true</code>.
+ The {@link xml::XMLLayout XMLLayout} returns <code>false</code>.
*/
virtual bool ignoresThrowable() const = 0;
};
diff --git a/src/main/include/log4cxx/logger.h b/src/main/include/log4cxx/logger.h
index fb42bc64..229e44eb 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -953,11 +953,12 @@ class LOG4CXX_EXPORT Logger :
* Is this logger is enabled for <code>DEBUG</code> level logging events?
*
* <p>By writing
- * <pre>
- * if(logger->isDebugEnabled()) {
+ * ~~~{.cpp}
+ * if(logger->isDebugEnabled()) {
* logger->debug("Component: " + std::to_string(componentNumber));
* }
- * </pre>you will not incur the cost of parameter construction
+ * ~~~
+ * you will not incur the cost of parameter construction
* (integer to string conversion plus string concatonation in this case)
* if debugging is disabled for <code>logger</code>.
* You avoid the cost constructing the message
@@ -965,9 +966,9 @@ class LOG4CXX_EXPORT Logger :
*
* <p>This function allows you to reduce the computational cost of
* disabled log debug statements compared to writing:
- * <pre>
+ * ~~~{.cpp}
* logger->debug("Component: " + std::to_string(componentNumber));
- * </pre>
+ * ~~~
*
* <p>On the other hand, if the <code>logger</code> is enabled for <code>DEBUG</code> logging events,
* you will incur the cost of evaluating whether the logger is
@@ -988,11 +989,12 @@ class LOG4CXX_EXPORT Logger :
* Is \c logger is enabled for <code>DEBUG</code> level logging events?
*
* <p>By writing
- * <pre>
+ * ~~~{.cpp}
* if(log4cxx::Logger::isDebugEnabledFor(logger)) {
* logger->forcedLog(log4cxx::Level::getDebug(), "Component: " + std::to_string(componentNumber));
* }
- * </pre>you minimise the computational cost
+ * ~~~
+ * you minimise the computational cost
* when \c logger is not enabled for <code>DEBUG</code> logging events.
* This function may be inlined thereby avoiding a function call
* as well as the cost constructing the message
@@ -1278,7 +1280,7 @@ class LOG4CXX_EXPORT Logger :
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
- @param val1 The value for the first placeholder within the pattern.
+ @param val The value for the first placeholder within the pattern.
@see #setResourceBundle
@@ -1360,7 +1362,7 @@ class LOG4CXX_EXPORT Logger :
@param level The level of the logging request.
@param key The key to be searched in the ResourceBundle.
@param locationInfo The location info of the logging request.
- @param val1 The value for the first placeholder within the pattern.
+ @param val The value for the first placeholder within the pattern.
@see #setResourceBundle
@@ -1642,7 +1644,7 @@ class LOG4CXX_EXPORT Logger :
/**
Set the level of this logger.
- <p>As in <pre> logger->setLevel(Level::getDebug()); </pre>
+ <p>As in <code>logger->setLevel(Level::getDebug());</code>
<p>Null values are admitted. */
virtual void setLevel(const LevelPtr level);
@@ -1957,7 +1959,7 @@ LOG4CXX_LIST_DEF(LoggerList, LoggerPtr);
/**
-Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events.
@param logger the logger to be used.
@param level the level to log.
@@ -1980,7 +1982,7 @@ Add a new logging event containing libfmt formatted <code>...</code> to attached
logger->forcedLog(level, fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
/**
-Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events..
+Add a new logging event containing \c message to attached appender(s) if this logger is enabled for \c events.
@param logger the logger to be used.
@param level the level to log.
@@ -1999,7 +2001,7 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_DEBUG(m_log, "AddMesh:"
<< " name " << meshName
<< " type 0x" << std:: hex << traits.Type
@@ -2008,7 +2010,7 @@ LOG4CXX_DEBUG(m_log, "AddMesh:"
<< " at " << obj->getBoundingBox().getCenter()
<< " +/- " << obj->getBoundingBox().getHalfSize()
);
-</pre>
+~~~
*/
#define LOG4CXX_DEBUG(logger, message) do { \
if (LOG4CXX_UNLIKELY(::log4cxx::Logger::isDebugEnabledFor(logger))) {\
@@ -2037,9 +2039,9 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_TRACE(m_log, "AddVertex:" << " p " << p[j] << " n " << n << ' ' << color);
-</pre>
+~~~
*/
#define LOG4CXX_TRACE(logger, message) do { \
@@ -2069,14 +2071,14 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message a valid r-value expression of an <code>operator<<(std::basic::ostream&. ...)</code> overload.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_INFO(m_log, surface->GetName()
<< " successfully planned " << std::fixed << std::setprecision(1) << ((plannedArea / (plannedArea + unplannedArea)) * 100.0) << "%"
<< " planned area " << std::fixed << std::setprecision(4) << plannedArea << "m^2"
<< " unplanned area " << unplannedArea << "m^2"
<< " planned segments " << surface->GetSegmentPlanCount() << " of " << surface->GetSegmentCount()
);
-</pre>
+~~~
*/
#define LOG4CXX_INFO(logger, message) do { \
if (::log4cxx::Logger::isInfoEnabledFor(logger)) {\
@@ -2105,12 +2107,12 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
catch (const std::exception& ex)
{
LOG4CXX_WARN(m_log, ex.what() << ": in " << m_task->GetParamFilePath());
}
-</pre>
+~~~
*/
#define LOG4CXX_WARN(logger, message) do { \
if (::log4cxx::Logger::isWarnEnabledFor(logger)) {\
@@ -2139,12 +2141,12 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
catch (std::exception& ex)
{
LOG4CXX_ERROR(m_log, ex.what() << " in AddScanData");
}
-</pre>
+~~~
*/
#define LOG4CXX_ERROR(logger, message) do { \
if (::log4cxx::Logger::isErrorEnabledFor(logger)) {\
@@ -2199,9 +2201,9 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
@param message the message string to log.
<p>Example:
-<pre>
+~~~{.cpp}
LOG4CXX_FATAL(m_log, m_renderSystem->getName() << " is not supported");
-</pre>
+~~~
*/
#define LOG4CXX_FATAL(logger, message) do { \
if (::log4cxx::Logger::isFatalEnabledFor(logger)) {\
diff --git a/src/main/include/log4cxx/logmanager.h b/src/main/include/log4cxx/logmanager.h
index 465f7187..5641aaae 100644
--- a/src/main/include/log4cxx/logmanager.h
+++ b/src/main/include/log4cxx/logmanager.h
@@ -54,14 +54,14 @@ class LOG4CXX_EXPORT LogManager
<p>Initally the guard is null. If the guard is
<code>null</code>, then invoking this method sets the logger
- factory and the guard. Following invocations will throw a {@link
- helpers::IllegalArgumentException IllegalArgumentException},
+ factory and the guard. Following invocations will throw a
+ {@link helpers::IllegalArgumentException IllegalArgumentException},
unless the previously set \c guard is passed as the second
parameter.
- <p>This allows a high-level component to set the {@link
- spi::RepositorySelector RepositorySelector} used by the
- LogManager.
+ <p>This allows a high-level component to set the
+ {@link spi::RepositorySelector RepositorySelector}
+ used by the LogManager.
*/
static void setRepositorySelector(spi::RepositorySelectorPtr selector,
@@ -218,8 +218,9 @@ class LOG4CXX_EXPORT LogManager
static void shutdown();
/**
- Reset all values contained in this current {@link
- spi::LoggerRepository LoggerRepository} to their default.
+ Reset all values contained in this current
+ {@link spi::LoggerRepository LoggerRepository}61
+ to their default.
*/
static void resetConfiguration();
}; // class LogManager
diff --git a/src/main/include/log4cxx/net/smtpappender.h b/src/main/include/log4cxx/net/smtpappender.h
index ae878384..d181027d 100644
--- a/src/main/include/log4cxx/net/smtpappender.h
+++ b/src/main/include/log4cxx/net/smtpappender.h
@@ -111,8 +111,8 @@ class LOG4CXX_EXPORT SMTPAppender : public AppenderSkeleton
/**
- The <code>SMTPAppender</code> requires a {@link
- Layout layout}. */
+ The <code>SMTPAppender</code> requires a <code>Layout</code>.
+ */
bool requiresLayout() const override;
/**
diff --git a/src/main/include/log4cxx/net/xmlsocketappender.h b/src/main/include/log4cxx/net/xmlsocketappender.h
index 7ca20bb6..ccd72887 100644
--- a/src/main/include/log4cxx/net/xmlsocketappender.h
+++ b/src/main/include/log4cxx/net/xmlsocketappender.h
@@ -27,20 +27,20 @@ namespace net
{
/**
-Sends {@link log4cxx::spi::LoggingEvent LoggingEvent} objects in XML format
- to a remote a log server, usually a XMLSocketNode.
+Sends LoggingEvent objects in XML format
+to a remote a log server, usually a XMLSocketNode.
<p>The XMLSocketAppender has the following properties:
- If sent to a XMLSocketNode, remote logging
- is non-intrusive as far as the log event is concerned. In other
-words, the event will be logged with the same time stamp, {@link
-NDC NDC}, location info as if it were logged locally by
+is non-intrusive as far as the log event is concerned. In other
+words, the event will be logged with the same time stamp,
+NDC, location info as if it were logged locally by
the client.
- XMLSocketAppenders use exclusively an XMLLayout. They ship an
-XML stream representing a {@link spi::LoggingEvent LoggingEvent} object
- to the server side.
+XML stream representing a LoggingEvent object
+to the server side.
- Remote logging uses the TCP protocol. Consequently, if
the server is reachable, then log events will eventually arrive
diff --git a/src/main/include/log4cxx/pattern/classnamepatternconverter.h b/src/main/include/log4cxx/pattern/classnamepatternconverter.h
index 067dee6a..3b324e20 100644
--- a/src/main/include/log4cxx/pattern/classnamepatternconverter.h
+++ b/src/main/include/log4cxx/pattern/classnamepatternconverter.h
@@ -38,7 +38,6 @@ class LOG4CXX_EXPORT ClassNamePatternConverter : public NamePatternConverter
public:
/**
* @param options options, may be null.
- * @param logger logger for diagnostic messages, may be null.
*/
ClassNamePatternConverter(const std::vector<LogString>& options);
diff --git a/src/main/include/log4cxx/pattern/propertiespatternconverter.h b/src/main/include/log4cxx/pattern/propertiespatternconverter.h
index f3aea02c..5ee9bfe8 100644
--- a/src/main/include/log4cxx/pattern/propertiespatternconverter.h
+++ b/src/main/include/log4cxx/pattern/propertiespatternconverter.h
@@ -49,8 +49,10 @@ class LOG4CXX_EXPORT PropertiesPatternConverter
END_LOG4CXX_CAST_MAP()
/**
- * @param options options, may be null.
- * @param logger logger for diagnostic messages, may be null.
+ * A Property bundle converter.
+ *
+ * @param name of the converter.
+ * @param option may be null.
*/
PropertiesPatternConverter(const LogString& name, const LogString& option);
diff --git a/src/main/include/log4cxx/patternlayout.h b/src/main/include/log4cxx/patternlayout.h
index 0a555e92..024f835d 100644
--- a/src/main/include/log4cxx/patternlayout.h
+++ b/src/main/include/log4cxx/patternlayout.h
@@ -32,7 +32,7 @@ LOG4CXX_LIST_DEF(FormattingInfoList, log4cxx::pattern::FormattingInfoPtr);
* A flexible layout configurable with pattern string.
*
* <p>
- * The goal of this class is to #format a {@link spi::LoggingEvent LoggingEvent} and
+ * The goal of this class is to format a {@link spi::LoggingEvent LoggingEvent} and
* return the results as a string. The results depend on the <em>conversion pattern</em>.
* </p>
*
@@ -57,10 +57,11 @@ LOG4CXX_LIST_DEF(FormattingInfoList, log4cxx::pattern::FormattingInfoPtr);
* <p>
* Let the conversion pattern be <strong>"%-5p [%t]: %m%n"</strong> and assume that the log4cxx
* environment was set to use a PatternLayout. Then the statements
- * <pre>
- * LoggerPtr root = Logger::getRoot();
+ * ~~~{.cpp}
+ * auto root = Logger::getRootLogger();
* root->debug("Message 1");
- * root->warn("Message 2");</pre>
+ * root->warn("Message 2");
+ * ~~~
* would yield the output
* <pre>
* DEBUG [main]: Message 1
diff --git a/src/main/include/log4cxx/propertyconfigurator.h b/src/main/include/log4cxx/propertyconfigurator.h
index 31d20ab4..416df08a 100644
--- a/src/main/include/log4cxx/propertyconfigurator.h
+++ b/src/main/include/log4cxx/propertyconfigurator.h
@@ -47,9 +47,8 @@ typedef std::shared_ptr<LoggerFactory> LoggerFactoryPtr;
class PropertyWatchdog;
/**
-Allows the configuration of log4cxx from an external file. See
-<b>{@link #doConfigure(const File&, log4cxx::spi::LoggerRepositoryPtr&)}</b>
-for the expected format.
+Allows the configuration of log4cxx from an external file.
+See {@link PropertyConfigurator#doConfigure doConfigure} for the expected format.
<p>It is sometimes useful to see how log4cxx is reading configuration
files. You can enable log4cxx internal logging by defining the
@@ -59,16 +58,15 @@ files. You can enable log4cxx internal logging by defining the
the file <b>log4j.properties</b> will be searched in the current directory.
If the file can be found, then it will
be fed to the
-{@link PropertyConfigurator#configure(const File& configFilename)}
+{@link PropertyConfigurator#configure(const File& configFilename) configure}
method.
<p>The <code>PropertyConfigurator</code> does not handle the
-advanced configuration features supported by the {@link
-xml::DOMConfigurator DOMConfigurator} such as
+advanced configuration features supported by the
+{@link xml::DOMConfigurator DOMConfigurator} such as
support for {@link spi::Filter Filters}, custom
{@link spi::ErrorHandler ErrorHandlers}, nested
-appenders such as the {@link AsyncAppender
-AsyncAppender}, etc.
+appenders such as the {@link AsyncAppender AsyncAppender}, etc.
<p>All option <em>values</em> admit variable substitution. The
syntax of variable substitution is similar to that of Unix
@@ -317,14 +315,14 @@ class LOG4CXX_EXPORT PropertyConfigurator :
/**
Read configuration options from <code>properties</code>.
- See #doConfigure(const File&, log4cxx::spi::LoggerRepositoryPtr&)
+ See {@link PropertyConfigurator#doConfigure doConfigure}
for the expected format.
*/
static void configure(helpers::Properties& properties);
/**
Read configuration options from <code>properties</code>.
- See #doConfigure(const File&, log4cxx::spi::LoggerRepositoryPtr&)
+ See {@link PropertyConfigurator#doConfigure doConfigure}
for the expected format.
*/
void doConfigure(helpers::Properties& properties,
@@ -335,9 +333,8 @@ class LOG4CXX_EXPORT PropertyConfigurator :
// --------------------------------------------------------------------------
protected:
/**
- Check the provided <code>Properties</code> object for a
- #loggerFactory
- entry specified by LOGGER_FACTORY_KEY. If such an entry
+ Check the provided <code>Properties</code> object for a LoggerFactory
+ entry specified by *log4j.loggerFactory*. If such an entry
exists, an attempt is made to create an instance using the default
constructor. This instance is used for subsequent Logger creations
within this configurator.
diff --git a/src/main/include/log4cxx/spi/filter.h b/src/main/include/log4cxx/spi/filter.h
index 46d7e55e..15eb05f6 100644
--- a/src/main/include/log4cxx/spi/filter.h
+++ b/src/main/include/log4cxx/spi/filter.h
@@ -62,8 +62,7 @@ event is logged without consulting the remaining filters.
<p>The philosophy of log4cxx filters is largely inspired from the
Linux ipchains.
-<p>Note that filtering is only supported by the {@link
-xml::DOMConfigurator DOMConfigurator}.
+<p>Note that filtering is only supported by the DOMConfigurator.
*/
class LOG4CXX_EXPORT Filter : public virtual OptionHandler
{
diff --git a/src/main/include/log4cxx/spi/loggerrepository.h b/src/main/include/log4cxx/spi/loggerrepository.h
index 1bb79040..d1fdf095 100644
--- a/src/main/include/log4cxx/spi/loggerrepository.h
+++ b/src/main/include/log4cxx/spi/loggerrepository.h
@@ -78,9 +78,10 @@ class LOG4CXX_EXPORT LoggerRepository : public virtual helpers::Object
virtual void emitNoAppenderWarning(const Logger* logger) = 0;
/**
- Get the repository-wide threshold. See {@link
- #setThreshold(const LevelPtr&) setThreshold}
- for an explanation. */
+ Get the repository-wide threshold.
+
+ See setThreshold for an explanation.
+ */
virtual LevelPtr getThreshold() const = 0;
virtual LoggerPtr getLogger(const LogString& name) = 0;
diff --git a/src/main/include/log4cxx/spi/optionhandler.h b/src/main/include/log4cxx/spi/optionhandler.h
index 1daeb6c3..e5e76ed1 100644
--- a/src/main/include/log4cxx/spi/optionhandler.h
+++ b/src/main/include/log4cxx/spi/optionhandler.h
@@ -45,10 +45,10 @@ class LOG4CXX_EXPORT OptionHandler : public virtual helpers::Object
options have been set. This is required for components which have
related options that remain ambigous until all are set.
- <p>For example, the FileAppender has the {@link
- FileAppender#setFile File} and {@link
- FileAppender#setAppend Append} options both of
- which are ambigous until the other is also set. */
+ <p>For example, the FileAppender has
+ the <code>File</code> and <b>Append</b> options both of
+ which are ambigous until the other is also set.
+ */
virtual void activateOptions(helpers::Pool& p) = 0;
diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in
index a383fa71..1a867fad 100644
--- a/src/site/doxy/Doxyfile.in
+++ b/src/site/doxy/Doxyfile.in
@@ -259,14 +259,6 @@ ALIASES =
# A mapping has the form "name=value". For example adding "class=itcl::class"
# will allow you to use the command class in the itcl::class meaning.
-TCL_SUBST =
-
-# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
-# only. Doxygen will then generate output that is more tailored for C. For
-# instance, some of the names that are used will be different. The list of all
-# members will be omitted, etc.
-# The default value is: NO.
-
OPTIMIZE_OUTPUT_FOR_C = NO
# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
@@ -1117,13 +1109,6 @@ CLANG_OPTIONS =
ALPHABETICAL_INDEX = YES
-# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
-# which the alphabetical index list will be split.
-# Minimum value: 1, maximum value: 20, default value: 5.
-# This tag requires that the tag ALPHABETICAL_INDEX is set to YES.
-
-COLS_IN_ALPHA_INDEX = 5
-
# In case all classes in a project start with a common prefix, all classes will
# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag
# can be used to specify a prefix (or a list of prefixes) that should be ignored
@@ -2185,12 +2170,6 @@ EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of 'which perl').
-# The default file (with absolute path) is: /usr/bin/perl.
-
-PERL_PATH = /usr/bin/perl
-
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
@@ -2204,15 +2183,6 @@ PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see:
-# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH =
-
# You can include diagrams made with dia in doxygen documentation. Doxygen will
# then run dia to produce the diagram and insert it in the documentation. The
# DIA_PATH tag allows you to specify the directory where the dia binary resides.
diff --git a/src/site/markdown/change-report-gh.md b/src/site/markdown/change-report-gh.md
index 223473e3..ca451c6a 100644
--- a/src/site/markdown/change-report-gh.md
+++ b/src/site/markdown/change-report-gh.md
@@ -25,25 +25,24 @@ Changelog {#changelog}
| Version | Date | Description |
| -------------------------------------------------------------------------------------- | ---------- | -------------------- |
-| [0.13.0](#0.13.0) | 2022-04-15 | Maintenance release |
-| [0.12.1](#0.12.1) | 2021-09-21 | Bugfix for 0.12.0 |
-| [0.12.0](#0.12.0) | 2021-05-01 | First release to require C++11. Updates for smart pointers. Standardization on CMake for building. |
-| [0.11.0](#0.11.0) | 2020-08-09 | Maintenance release. |
-| [0.10.0](#0.10.0) | 2008-04-03 | First Apache release |
-| [0.9.7](#0.9.7) | 2004-05-10 | |
-| [0.9.6](#0.9.6) | 2004-04-11 | |
-| [0.9.5](#0.9.5) | 2004-02-04 | |
-| [0.9.4](#0.9.4) | 2003-10-25 | |
-| [0.9.3](#0.9.3) | 2003-09-19 | |
-| [0.9.2](#0.9.2) | 2003-08-10 | |
-| [0.9.1](#0.9.1) | 2003-08-06 | |
-| [0.9.0](#0.9.0) | 2003-08-06 | |
-| [0.1.1](#0.1.1) | 2003-07-09 | |
-| [0.1.0](#0.1.0) | 2003-07-08 | |
-| [0.0.1](#0.0.1) | 2003-05-31 | |
-
-<a name="0.13.0"/>
-## Release 0.13.0 - 2022-04-15
+| [0.13.0](#rel_13_0) | 2022-04-15 | Maintenance release |
+| [0.12.1](#rel_12_1) | 2021-09-21 | Bugfix for 0.12.0 |
+| [0.12.0](#rel_12_0) | 2021-05-01 | First release to require C++11. Updates for smart pointers. Standardization on CMake for building. |
+| [0.11.0](#rel_11_0) | 2020-08-09 | Maintenance release. |
+| [0.10.0](#rel_10_0) | 2008-04-03 | First Apache release |
+| [0.9.7](#rel_9_7) | 2004-05-10 | |
+| [0.9.6](#rel_9_6) | 2004-04-11 | |
+| [0.9.5](#rel_9_5) | 2004-02-04 | |
+| [0.9.4](#rel_9_4) | 2003-10-25 | |
+| [0.9.3](#rel_9_3) | 2003-09-19 | |
+| [0.9.2](#rel_9_2) | 2003-08-10 | |
+| [0.9.1](#rel_9_1) | 2003-08-06 | |
+| [0.9.0](#rel_9_0) | 2003-08-06 | |
+| [0.1.1](#rel_1_1) | 2003-07-09 | |
+| [0.1.0](#rel_1_0) | 2003-07-08 | |
+| [0.0.1](#rel_0_1) | 2003-05-31 | |
+
+## Release 0.13.0 - 2022-04-15 {#rel_13_0}
This release fixes a number of issues. Notable new features include the
ability to block signals from threads that the library creates, automatic
@@ -111,8 +110,7 @@ Wish
shared\_mutex
-<a name="0.12.0"/>
-## Release 0.12.1 - 2021-09-21
+## Release 0.12.1 - 2021-09-21 {#rel_12_1}
This is a minor bugfix release to fix issues found with 0.12.0. Notably, this version fixes a bug
where a multithreaded application would crash when using a rolling file.
@@ -126,8 +124,7 @@ Bug
log4cxx fails to build on Centos 7.6 / g++ 4.8.5 / Boost 1.53
-<a name="0.12.0"/>
-## Release 0.12.0 - 2021-05-01
+## Release 0.12.0 - 2021-05-01 {#rel_12_0}
This is the first release to require a minimum version of C++11. This means that all objects in log4cxx
are now created using `std::shared_ptr` as the smart pointer implementation.
@@ -189,8 +186,7 @@ Improvement
- \[[LOGCXX-523](https://issues.apache.org/jira/browse/LOGCXX-523)\] -
Add in error handling for rollover errors
-<a name="0.11.0"/>
-### Release 0.11.0 - 2020-08-09
+## Release 0.11.0 - 2020-08-09 {#rel_11_0}
| | | |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -250,7 +246,7 @@ Improvement
|  | Please make sure that the LOG4CXX\_\* macro's can be used as ordinary statements. Fixes [LOGCXX-319](https://issues.apache.org/jira/browse/LOGCXX-319). | |
|  | Log4cxx triggers locking inversion which can result in a deadlock. Fixes [LOGCXX-317](https://issues.apache.org/jira/browse/LOGCXX-317). | |
|  | Build process fails in case of absence of iconv support in apr-util Fixes [LOGCXX-313](https://issues.apache.org/jira/browse/LOGCXX-313). | |
-|  | Property/DOMConfigurator::configureAndWatch can continue to run after APR termination Fixes [LOGCXX-305](https://issues.apache.org/jira/browse/LOGCXX-305). | |
+|  | Property/xml::DOMConfigurator::configureAndWatch can continue to run after APR termination Fixes [LOGCXX-305](https://issues.apache.org/jira/browse/LOGCXX-305). | |
|  | BasicConfigurator::configure results in writer not set warning. Fixes [LOGCXX-304](https://issues.apache.org/jira/browse/LOGCXX-304). | |
|  | DOMConfigurator does not set ErrorHandler. Fixes [LOGCXX-303](https://issues.apache.org/jira/browse/LOGCXX-303). | |
|  | ODBCAppender connection settings broken (or just have changed). Fixes [LOGCXX-300](https://issues.apache.org/jira/browse/LOGCXX-300). | |
@@ -290,8 +286,7 @@ Improvement
|  | Documented C (class) and M (method) log format keywords. | |
|  | LocationInfo for Borland C++ Builder and successors improved. | |
-<a name="0.10.0"/>
-### Release 0.10.0 - 2008-04-03
+## Release 0.10.0 - 2008-04-03 {#rel_10_0}
| | | |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -319,8 +314,8 @@ Improvement
|  | Drop src/performance Fixes [LOGCXX-232](https://issues.apache.org/jira/browse/LOGCXX-232). | |
|  | Deadlock in AsyncAppender Fixes [LOGCXX-231](https://issues.apache.org/jira/browse/LOGCXX-231). | |
|  | Align ant build options with automake Fixes [LOGCXX-230](https://issues.apache.org/jira/browse/LOGCXX-230). | |
-|  | Remove @author tags Fixes [LOGCXX-228](https://issues.apache.org/jira/browse/LOGCXX-228). | |
-|  | Remove @since tags Fixes [LOGCXX-227](https://issues.apache.org/jira/browse/LOGCXX-227). | |
+|  | Remove \@author tags Fixes [LOGCXX-228](https://issues.apache.org/jira/browse/LOGCXX-228). | |
+|  | Remove \@since tags Fixes [LOGCXX-227](https://issues.apache.org/jira/browse/LOGCXX-227). | |
|  | Default configurator uses \*.properties in preference to \*.xml Fixes [LOGCXX-226](https://issues.apache.org/jira/browse/LOGCXX-226). | |
|  | Migrate unit tests from LGPL'd CPPUNIT to an ASL'd testing framework Fixes [LOGCXX-225](https://issues.apache.org/jira/browse/LOGCXX-225). | |
|  | trunk compile error. Fixes [LOGCXX-222](https://issues.apache.org/jira/browse/LOGCXX-222). | |
@@ -501,8 +496,7 @@ Improvement
|  | Missing \#else Fixes [LOGCXX-3](https://issues.apache.org/jira/browse/LOGCXX-3). | |
|  | logger.h includes config.h Fixes [LOGCXX-2](https://issues.apache.org/jira/browse/LOGCXX-2). | |
-<a name="0.9.7"/>
-### Release 0.9.7 - 2004-05-10
+## Release 0.9.7 - 2004-05-10 {#rel_9_7}
| | | |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -517,8 +511,7 @@ Improvement
|  | Logging macros can be used without explicity declaring the use of log4cxx namespace. | |
|  | Fixed static library unresolved externals for msvc 6 and 7.1 | |
-<a name="0.9.6"/>
-### Release 0.9.6 - 2004-04-11
+## Release 0.9.6 - 2004-04-11 {#rel_9_6}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -- |
@@ -532,8 +525,7 @@ Improvement
|  | Added TimeZone configuration to PatternLayout (bug 912563) | |
|  | Support of the DailyRollingFileAppender (feature request 842765) | |
-<a name="0.9.5"/>
-### Release 0.9.5 - 2004-02-04
+## Release 0.9.5 - 2004-02-04 {#rel_9_5}
| | | |
| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -553,8 +545,7 @@ Improvement
|  | Fixed compilations problems with unicode. | |
|  | Fixed SocketAppender bug concerning MDC and NDC. | |
-<a name="0.9.4"/>
-### Release 0.9.4 - 2003-10-25
+## Release 0.9.4 - 2003-10-25 {#rel_9_4}
| | | |
| ------------------------------------------------------------------- | --------------------------------------------------------- | -- |
@@ -565,8 +556,7 @@ Improvement
|  | Fixed threading configuration problems (bug 809125) | |
|  | Fixed miscellaneous MSVC and cygwin compilation problems. | |
-<a name="0.9.3"/>
-### Release 0.9.3 - 2003-09-19
+## Release 0.9.3 - 2003-09-19 {#rel_9_3}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -- |
@@ -581,8 +571,7 @@ Improvement
|  | Added new tests | |
|  | Added benchmarks | |
-<a name="0.9.2"/>
-### Release 0.9.2 - 2003-08-10
+## Release 0.9.2 - 2003-08-10 {#rel_9_2}
| | | |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -- |
@@ -592,8 +581,7 @@ Improvement
|  | Long events (\> 1024 chars) are now supported in the class XMLSocketAppender. | |
|  | Carriage returns have been normalized in the class XMLLayout. | |
-<a name="0.9.1"/>
-### Release 0.9.1 - 2003-08-06
+## Release 0.9.1 - 2003-08-06 {#rel_9_1}
| | | |
| ------------------------------------------------------------------- | ------------------------------------------------------------ | -- |
@@ -603,8 +591,7 @@ Improvement
|  | Added MSVC 6.0 static libraty project. | |
|  | Default configuration for the SMTP options is "no". | |
-<a name="0.9.0"/>
-### Release 0.9.0 - 2003-08-06
+## Release 0.9.0 - 2003-08-06 {#rel_9_0}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------- | -- |
@@ -619,8 +606,7 @@ Improvement
|  | Added MSVC 6.0 'Unicode Debug' and 'Unicode Release' targets | |
|  | Added Java like System class. | |
-<a name="0.1.1"/>
-### Release 0.1.1 - 2003-07-09
+## Release 0.1.1 - 2003-07-09 {#rel_1_1}
| | | |
| ---------------------------------------------------------------- | ------------------------------------------------------------------- | -- |
@@ -628,8 +614,7 @@ Improvement
|  | Fixed MSVC 6.0 compilation problems concerning the 'Release' target | |
|  | Added MSVC 6.0 tests projects | |
-<a name="0.1.0"/>
-### Release 0.1.0 - 2003-07-08
+## Release 0.1.0 - 2003-07-08 {#rel_1_0}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
@@ -645,8 +630,7 @@ Improvement
|  | Port of the "Map Diagnostic Context" (MDC) class | |
|  | Added 13 tests (try make check) | |
-<a name="0.0.1"/>
-### Release 0.0.1 - 2003-05-31
+## Release 0.0.1 - 2003-05-31 {#rel_0_1}
| | | |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
diff --git a/src/site/markdown/development/build-cmake.md b/src/site/markdown/development/build-cmake.md
index b8837a5b..242430b9 100644
--- a/src/site/markdown/development/build-cmake.md
+++ b/src/site/markdown/development/build-cmake.md
@@ -43,19 +43,19 @@ $ sudo make install
Windows Example:
Building and testing Log4cxx on a Microsoft Windows with APR, Expat and APR-Util built from source
-extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%\Libraries.
+extracted into apr-1.7.0, libexpat(from github) and apr-util-1.6.1 in %HOMEPATH%/Libraries.
~~~
-$ cd %HOMEPATH%\Libraries
-$ cmake -S libexpat\expat -B buildtrees\expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\expat --target install --config Release
-$ cmake -S apr-1.7.0 -B buildtrees\apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\apr --target install --config Release
-$ set CMAKE_PREFIX_PATH=%HOMEPATH%\Libraries\installed
-$ cmake -S apr-util-1.6.1 -B buildtrees\apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\apr-util --target install --config Release
-$ cmake -S apache-Log4cxx-x.x.x -B buildtrees\Log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%\Libraries\installed
-$ cmake --build buildtrees\Log4cxx --target install --config Release
+$ cd %HOMEPATH%/Libraries
+$ cmake -S libexpat/expat -B buildtrees/expat -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/expat --target install --config Release
+$ cmake -S apr-1.7.0 -B buildtrees/apr -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/apr --target install --config Release
+$ set CMAKE_PREFIX_PATH=%HOMEPATH%/Libraries/installed
+$ cmake -S apr-util-1.6.1 -B buildtrees/apr-util -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/apr-util --target install --config Release
+$ cmake -S apache-Log4cxx-x.x.x -B buildtrees/Log4cxx -DCMAKE_INSTALL_PREFIX=%HOMEPATH%/Libraries/installed
+$ cmake --build buildtrees/Log4cxx --target install --config Release
~~~
## ccmake options
@@ -136,7 +136,7 @@ The easiest way to get dependencies installed is to use vcpkg(for APR/expat), an
utilities(zip, grep, sed).
Msys2 can be downloaded from: https://www.msys2.org/
-By default, this will be installed under C:\msys2, so you can add that to the build PATH by setting
+By default, this will be installed under C:\\msys2, so you can add that to the build PATH by setting
LOG4CXX_TEST_PROGRAM_PATH=C:/msys64/usr/bin in your build settings.
For vcpkg, follow the directions at https://github.com/microsoft/vcpkg#quick-start-windows and then install
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index 2e9053b8..da484720 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -1,4 +1,4 @@
-Usage {#usage}
+Loggers, Appenders and Layouts {#usage}
===
<!--
Note: License header cannot be first, as doxygen does not generate
@@ -22,14 +22,12 @@ Usage {#usage}
-->
[TOC]
-# Loggers {#loggers}
-
Log4cxx has three main components: *loggers*, *appenders* and *layouts*.
These three types of components work together to enable developers to
log messages according to message type and level, and to control at
runtime how these messages are formatted and where they are reported.
-## Hierarchy {#hierarchy}
+# Hierarchy {#hierarchy}
The first and foremost advantage of any logging API over plain
`std::cout` resides in its ability to disable certain log statements
@@ -89,7 +87,7 @@ Some of the basic methods in the Logger class are listed below.
#define LOG4CXX_FATAL(logger, expression) ...
~~~
-## Levels {#levels}
+# Levels {#levels}
Loggers *may* be assigned levels. The pre-defined levels: TRACE, DEBUG,
INFO, WARN, ERROR and FATAL are defined in the
@@ -162,7 +160,7 @@ In example 4, the loggers *root* and *X* and are assigned the levels
their level value from their nearest parent *X* having an assigned
level.
-## Requests {#requests}
+# Requests {#requests}
Logging requests are made by invoking a method of a logger instance,
preferrably through the use of LOG4CXX\_INFO or similar macros which
@@ -261,7 +259,7 @@ name the loggers as desired.
Nevertheless, naming loggers after the class where they are located
seems to be the best strategy known so far.
-# Appenders and Layouts {#appenders-and-layouts}
+# Appenders {#appenders}
The ability to selectively enable or disable logging requests based on
their logger is only part of the picture. Log4cxx allows logging
@@ -292,7 +290,7 @@ appender accumulation is no longer additive by
The rules governing appender additivity are summarized below.
-## Appender Additivity {#additivity}
+## Additivity {#appender-additivity}
The output of a log statement of logger *C* will go to all the appenders
in *C* and its ancestors. This is the meaning of the term "appender
@@ -416,7 +414,24 @@ is invoked on the first call to the com::foo::getLogger() function
and its destructor is automatically called during application exit.
\include com/foo/config1.cpp
-## Request Formatting {#formatting}
+## Default Initialization {#default-initialization}
+
+The Log4cxx library does not make any assumptions about its environment.
+In particular, when initially created the root [Logger](@ref log4cxx.Logger) has no appender.
+However the library will attempt automatic configuration.
+
+If the LoggerRepositoy is not yet configured on the first call to
+[getLogger](@ref log4cxx.LogManager.getLogger) of [LogManager](@ref log4cxx.LogManager),
+the [configure](@ref log4cxx.DefaultConfigurator.configure) method
+of [DefaultConfigurator](@ref log4cxx.DefaultConfigurator) is called
+via [ensureIsConfigured](@ref log4cxx.spi.LoggerRepository.ensureIsConfigured) method
+of [LoggerRepository](@ref log4cxx.spi.LoggerRepository).
+
+To use automatic configuration with a non-standard file name
+create and use your own wrapper for [getLogger](@ref log4cxx.LogManager.getLogger).
+A full example can be seen in the \ref com/foo/config3.cpp file.
+
+# Layouts {#layouts}
The invocation of the
[BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.configure)
@@ -445,7 +460,7 @@ This version of *config.cpp* instructs [PropertyConfigurator](@ref log4cxx.Prope
to use the *MyApp.properties* file to configure Log4cxx.
A more realistic approach would (for example)
use the current module name to select the configuration file
-(see the \ref UserLib/logmanager.cpp file for how to do this).
+(see the \ref com/foo/config3.cpp file for how to do this).
Here is a sample *MyApp.properties* configuration file that results in exactly same output
as the previous [BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.configure) based example.
@@ -459,7 +474,7 @@ as the previous [BasicConfigurator::configure](@ref log4cxx.BasicConfigurator.co
# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
- log4j.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n
+ log4j.appender.A1.layout.ConversionPattern=%r [%t] %-5p %c %x - %m%n
~~~
It can be noticed that the PropertyConfigurator file format is the same
@@ -518,37 +533,6 @@ forwarded logging events to a remote Log4cxx server, which would log
according to local server policy, for example by forwarding the log
event to a second Log4cxx server.
-## Default Initialization {#default-initialization}
-
-The Log4cxx library does not make any assumptions about its environment.
-In particular, when initially created the root [Logger](@ref log4cxx.Logger) has no appender.
-However the library will attempt automatic configuration.
-
-If the LoggerRepositoy is not yet configured on the first call to
-[getLogger](@ref log4cxx.LogManager.getLogger) of [LogManager](@ref log4cxx.LogManager),
-the [configure](@ref log4cxx.DefaultConfigurator.configure) method
-of [DefaultConfigurator](@ref log4cxx.DefaultConfigurator) is called
-via [ensureIsConfigured](@ref log4cxx.spi.LoggerRepository.ensureIsConfigured) method
-of [LoggerRepository](@ref log4cxx.spi.LoggerRepository).
-
-To use automatic configuration with a non-standard file name
-create and use your own wrapper for [getLogger](@ref log4cxx.LogManager.getLogger).
-A full example can be seen in the \ref UserLib/logmanager.cpp file.
-
-# Internal Debugging {#internal-debugging}
-
-Because Log4cxx is a logging library, we can't use it to output errors from
-the library itself. There are several ways to activate internal logging:
-
-1. Configure the library directly by calling the
-[LogLog::setInternalDebugging](@ref log4cxx.helpers.LogLog.setInternalDebugging)
-method
-2. If using a properties file, set the value `log4j.debug=true` in your configuration file
-3. If using an XML file, set the attribute `internalDebug=true` in the root node
-4. From the environment: `LOG4CXX_DEBUG=true`
-
-All error and warning messages are sent to stderr.
-
# Nested Diagnostic Contexts {#nested-diagnostic-contexts}
Most real-world systems have to deal with multiple clients
@@ -617,93 +601,6 @@ Log4cxx releases support multiple hierarchy trees. This enhancement
allows each virtual host to possess its own copy of the logger
hierarchy.
-# Performance {#performance}
-
-One of the often-cited arguments against logging is its computational
-cost. This is a legitimate concern as even moderately sized applications
-can generate thousands of log requests. Much effort was spent measuring
-and tweaking logging performance. Log4cxx claims to be fast and
-flexible: speed first, flexibility second.
-
-The user should be aware of the following performance issues.
-
-1. **Logging performance when logging is turned off.**
-
- The LOG4CXX\_DEBUG and similar macros have a
- cost of an in-lined null pointer check plus an integer comparison
- when the logger not currently enabled for that level.
- The other terms inside the macro are not evaluated.
-
- When the level is enabled for a logger but the logging hierarchy is turned off
- entirely or just for a set of levels, the cost of a log request consists
- of a method invocation plus an integer comparison.
-
-2. **Actually outputting log messages**
-
- This is the cost of formatting the log output and sending it to its
- target destination. Here again, a serious effort was made to make
- layouts (formatters) perform as quickly as possible. The same is
- true for appenders.
-
-3. **The cost of changing a logger's level.**
-
- The threshold value stored in any child logger is updated.
- This is done iterating over the map of all known logger objects
- and walking the hierarchy of each.
-
- There has been a serious effort to make this hierarchy walk to be as
- fast as possible. For example, child loggers link only to their
- existing ancestors. In the *BasicConfigurator* example shown
- earlier, the logger named *com.foo.Bar* is linked directly to the
- root logger, thereby circumventing the nonexistent *com* or
- *com.foo* loggers. This significantly improves the speed of the
- walk, especially in "sparse" hierarchies.
-
-## Removing log statements {#removing-log-statements}
-
-Sometimes, you may want to remove all log statements from your program,
-either for speed purposes or to remove sensitive information. This can easily
-be accomplished at build-time when using the standard `LOG4CXX_[level]` macros
-(`LOG4CXX_TRACE`, `LOG4CXX_DEBUG`, `LOG4CXX_INFO`, `LOG4CXX_WARN`,
-`LOG4CXX_ERROR`, `LOG4CXX_FATAL`).
-
-Log statements can be removed either above a certain level, or they
-can be disabled entirely.
-
-For example, if we want to remove all log statements within our program
-that use the `LOG4CXX_[level]` family of macros, add a preprocessor
-definition `LOG4CXX_THRESHOLD` set to 50001
-or greater. This will ensure that any log statement that uses the
-`LOG4CXX_[level]`-macro will be compiled out of the program. To remove
-all log statements at `DEBUG` or below, set `LOG4CXX_THRESHOLD` to a
-value between 10001-20000.
-
-The levels are set as follows:
-
-|Logger Level|Integer Value|
-|------------|-------------|
-|TRACE |5000 |
-|DEBUG |10000 |
-|INFO |20000 |
-|WARN |30000 |
-|ERROR(1) |40000 |
-|FATAL |50000 |
-
-(1) The `LOG4CXX_ASSERT` macro is the same level as `LOG4CXX_ERROR`
-
-Note that this has no effect on other macros, such as using the
-`LOG4CXX_LOG`, `LOG4CXX_LOGLS`, or `LOG4CXX_L7DLOG` family of macros.
-
-## Removing location information {#removing-location-information}
-
-Whenever you log a message with Log4cxx, metadata about the location of the
-logging statement is captured as well through the preprocessor. This includes
-the file name, the method name, and the line number. If you would not like to
-include this information in your build but you still wish to keep the log
-statements, define `LOG4CXX_DISABLE_LOCATION_INFO` in your build system. This
-will allow log messages to still be created, but the location information
-will be invalid.
-
# Logging Custom Types {#custom-types}
Often, the data that needs to be logged is not just standard data types
@@ -789,6 +686,107 @@ dropping the log message and not consulting any other filters.
See the documentation for [Filter](@ref log4cxx.spi.Filter) for some more
information, or view a [configuration sample](@ref configuration-samples).
+# Internal Debugging {#internal-debugging}
+
+Because Log4cxx is a logging library, we can't use it to output errors from
+the library itself. There are several ways to activate internal logging:
+
+1. Configure the library directly by calling the
+[LogLog::setInternalDebugging](@ref log4cxx.helpers.LogLog.setInternalDebugging)
+method
+2. If using a properties file, set the value `log4j.debug=true` in your configuration file
+3. If using an XML file, set the attribute `internalDebug=true` in the root node
+4. From the environment: `LOG4CXX_DEBUG=true`
+
+All error and warning messages are sent to stderr.
+
+# Overhead {#request-cost}
+
+One of the often-cited arguments against logging is its computational
+cost. This is a legitimate concern as even moderately sized applications
+can generate thousands of log requests. Much effort was spent measuring
+and tweaking logging performance. Log4cxx claims to be fast and
+flexible: speed first, flexibility second.
+
+For performance sensitive applications, you should be aware of the following.
+
+1. **Logging performance when logging is turned off.**
+
+ The LOG4CXX\_DEBUG and similar macros have a
+ cost of an in-lined null pointer check plus an integer comparison
+ when the logger not currently enabled for that level.
+ The other terms inside the macro are not evaluated.
+
+ When the level is enabled for a logger but the logging hierarchy is turned off
+ entirely or just for a set of levels, the cost of a log request consists
+ of a method invocation plus an integer comparison.
+
+2. **Actually outputting log messages**
+
+ This is the cost of formatting the log output and sending it to its
+ target destination. Here again, a serious effort was made to make
+ layouts (formatters) perform as quickly as possible. The same is
+ true for appenders.
+
+3. **The cost of changing a logger's level.**
+
+ The threshold value stored in any child logger is updated.
+ This is done iterating over the map of all known logger objects
+ and walking the hierarchy of each.
+
+ There has been a serious effort to make this hierarchy walk to be as
+ fast as possible. For example, child loggers link only to their
+ existing ancestors. In the *BasicConfigurator* example shown
+ earlier, the logger named *com.foo.Bar* is linked directly to the
+ root logger, thereby circumventing the nonexistent *com* or
+ *com.foo* loggers. This significantly improves the speed of the
+ walk, especially in "sparse" hierarchies.
+
+## Removing log statements {#removing-log-statements}
+
+Sometimes, you may want to remove all log statements from your program,
+either for speed purposes or to remove sensitive information. This can easily
+be accomplished at build-time when using the standard `LOG4CXX_[level]` macros
+(`LOG4CXX_TRACE`, `LOG4CXX_DEBUG`, `LOG4CXX_INFO`, `LOG4CXX_WARN`,
+`LOG4CXX_ERROR`, `LOG4CXX_FATAL`).
+
+Log statements can be removed either above a certain level, or they
+can be disabled entirely.
+
+For example, if we want to remove all log statements within our program
+that use the `LOG4CXX_[level]` family of macros, add a preprocessor
+definition `LOG4CXX_THRESHOLD` set to 50001
+or greater. This will ensure that any log statement that uses the
+`LOG4CXX_[level]`-macro will be compiled out of the program. To remove
+all log statements at `DEBUG` or below, set `LOG4CXX_THRESHOLD` to a
+value between 10001-20000.
+
+The levels are set as follows:
+
+|Logger Level|Integer Value|
+|------------|-------------|
+|TRACE |5000 |
+|DEBUG |10000 |
+|INFO |20000 |
+|WARN |30000 |
+|ERROR(1) |40000 |
+|FATAL |50000 |
+
+(1) The `LOG4CXX_ASSERT` macro is the same level as `LOG4CXX_ERROR`
+
+Note that this has no effect on other macros, such as using the
+`LOG4CXX_LOG`, `LOG4CXX_LOGLS`, or `LOG4CXX_L7DLOG` family of macros.
+
+## Removing location information {#removing-location-information}
+
+Whenever you log a message with Log4cxx, metadata about the location of the
+logging statement is captured as well through the preprocessor. This includes
+the file name, the method name, and the line number. If you would not like to
+include this information in your build but you still wish to keep the log
+statements, define `LOG4CXX_DISABLE_LOCATION_INFO` in your build system. This
+will allow log messages to still be created, but the location information
+will be invalid.
+
# Conclusions {#conclusions}
Apache Log4cxx is a popular logging package written in C++. One of its
@@ -805,9 +803,10 @@ formats. The Log4cxx package is designed so that log statements can
remain in shipped code without incurring a heavy performance cost.
\example auto-configured.cpp
-This is an example of logging in static initialization code.
+This is an example of logging in static initialization code and
+using the current module name to select the Log4cxx configuration file.
-\example UserLib/logmanager.cpp
+\example com/foo/config3.cpp
This file is an example of how to use the current module name to select the Log4cxx configuration file.
\example format-string.cpp