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 2023/06/23 02:25:59 UTC

[logging-log4cxx] branch master updated: Improve documentation by adding example code (#220)

This is an automated email from the ASF dual-hosted git repository.

swebb2066 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git


The following commit(s) were added to refs/heads/master by this push:
     new a330ce95 Improve documentation by adding example code (#220)
a330ce95 is described below

commit a330ce9516374b962b0b2bd22afcad8021992709
Author: Stephen Webb <st...@ieee.org>
AuthorDate: Fri Jun 23 12:25:54 2023 +1000

    Improve documentation by adding example code (#220)
---
 src/examples/cpp/CMakeLists.txt                    | 19 +++++-------
 src/examples/cpp/custom-appender.cpp               | 13 ++++----
 ...-configured.xml => example-auto-configured.xml} |  0
 ...om-appender.xml => example-custom-appender.xml} |  0
 src/examples/cpp/trivial.cpp                       | 31 ++++++++-----------
 src/site/markdown/extending.md                     |  9 ++++--
 src/site/markdown/usage.md                         | 36 ++++++----------------
 7 files changed, 45 insertions(+), 63 deletions(-)

diff --git a/src/examples/cpp/CMakeLists.txt b/src/examples/cpp/CMakeLists.txt
index afd396cd..643ca743 100644
--- a/src/examples/cpp/CMakeLists.txt
+++ b/src/examples/cpp/CMakeLists.txt
@@ -29,28 +29,25 @@ else()
 endif()
 
 foreach(exampleName IN LISTS ALL_LOG4CXX_EXAMPLES)
-    add_executable(${exampleName} ${exampleName}.cpp)
+    set(PROGRAM_NAME "example-${exampleName}")
+    add_executable(${PROGRAM_NAME} ${exampleName}.cpp)
     if(${exampleName} STREQUAL MyApp2)
-        target_sources(${exampleName} PRIVATE com/foo/config2.cpp com/foo/bar.cpp)
+        target_sources(${PROGRAM_NAME} PRIVATE com/foo/config2.cpp com/foo/bar.cpp)
     endif()
     if(${exampleName} STREQUAL auto-configured)
-        target_sources(${exampleName} PRIVATE com/foo/config3.cpp )
+        target_sources(${PROGRAM_NAME} 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})
+    target_compile_definitions(${PROGRAM_NAME} PRIVATE ${EXAMPLE_COMPILE_DEFINITIONS} ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
+    target_include_directories(${PROGRAM_NAME} PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
+    target_link_libraries(${PROGRAM_NAME} PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${EXPAT_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS})
     if( WIN32 )
-        set_target_properties(${exampleName} PROPERTIES
+        set_target_properties(${PROGRAM_NAME} PROPERTIES
           VS_DEBUGGER_ENVIRONMENT "PATH=${ESCAPED_PATH}"
           VS_DEBUGGER_WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
         )
     endif()
 endforeach()
 
-configure_file( custom-appender.xml
-    ${CMAKE_CURRENT_BINARY_DIR}/custom-appender.xml
-    COPYONLY )
-
 # Custom handling for format string example, since it utilizes libfmt
 if(${fmt_FOUND})
     add_executable( format-string format-string.cpp )
diff --git a/src/examples/cpp/custom-appender.cpp b/src/examples/cpp/custom-appender.cpp
index 51c485e8..1507968d 100644
--- a/src/examples/cpp/custom-appender.cpp
+++ b/src/examples/cpp/custom-appender.cpp
@@ -15,9 +15,7 @@
  * limitations under the License.
  */
 
-#include <stdlib.h>
 #include <log4cxx/basicconfigurator.h>
-#include <log4cxx/helpers/object.h>
 #include <log4cxx/appenderskeleton.h>
 #include <log4cxx/helpers/stringhelper.h>
 #include <log4cxx/xml/domconfigurator.h>
@@ -60,11 +58,14 @@ IMPLEMENT_LOG4CXX_OBJECT(NullWriterAppender)
 
 }
 
-int main( int argc, char** argv ){
-	log4cxx::xml::DOMConfigurator::configure( "custom-appender.xml" );
+int main( int argc, char** argv )
+{
+    using namespace log4cxx;
 
-	log4cxx::LoggerPtr rootLogger = log4cxx::Logger::getRootLogger();
-	log4cxx::LoggerPtr nullLogger = log4cxx::Logger::getLogger( "NullLogger" );
+	xml::DOMConfigurator::configure( "example-custom-appender.xml" );
+
+	LoggerPtr rootLogger = Logger::getRootLogger();
+	LoggerPtr nullLogger = Logger::getLogger( "NullLogger" );
 
 	LOG4CXX_INFO( rootLogger, "This is some root message" );
 	LOG4CXX_INFO( nullLogger, "This message will be discarded" );
diff --git a/src/examples/cpp/auto-configured.xml b/src/examples/cpp/example-auto-configured.xml
similarity index 100%
rename from src/examples/cpp/auto-configured.xml
rename to src/examples/cpp/example-auto-configured.xml
diff --git a/src/examples/cpp/custom-appender.xml b/src/examples/cpp/example-custom-appender.xml
similarity index 100%
rename from src/examples/cpp/custom-appender.xml
rename to src/examples/cpp/example-custom-appender.xml
diff --git a/src/examples/cpp/trivial.cpp b/src/examples/cpp/trivial.cpp
index 6e8726e2..23268f25 100644
--- a/src/examples/cpp/trivial.cpp
+++ b/src/examples/cpp/trivial.cpp
@@ -14,40 +14,35 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-#include <log4cxx/logstring.h>
 #include <stdlib.h>
 #include <log4cxx/logger.h>
 #include <log4cxx/basicconfigurator.h>
-#include <log4cxx/helpers/exception.h>
 #include <log4cxx/ndc.h>
 #include <locale.h>
 
 using namespace log4cxx;
-using namespace log4cxx::helpers;
 
 int main()
 {
-    setlocale(LC_ALL, "");
+    setlocale(LC_ALL, ""); // Use the user-preferred locale
     int result = EXIT_SUCCESS;
     try
     {
-                BasicConfigurator::configure();
-                LoggerPtr rootLogger = Logger::getRootLogger();
+        BasicConfigurator::configure();
+        LoggerPtr rootLogger = Logger::getRootLogger();
 
-                NDC::push("trivial context");
-
-                LOG4CXX_DEBUG(rootLogger, "debug message");
-                LOG4CXX_INFO(rootLogger, "info message");
-                LOG4CXX_WARN(rootLogger, "warn message");
-                LOG4CXX_ERROR(rootLogger, "error message");
-                LOG4CXX_FATAL(rootLogger, "fatal message");
-
-                NDC::pop();
-        }
-        catch(std::exception&)
+        NDC context1("[outer]");
+        LOG4CXX_INFO(rootLogger, "info message"); // log entry contains "[outer]"
         {
-                result = EXIT_FAILURE;
+            NDC context2("[inner]");
+            LOG4CXX_DEBUG(rootLogger, "debug message"); // log entry contains "[outer] [inner]"
         }
+        LOG4CXX_WARN(rootLogger, "warn message"); // log entry contains "[outer]"
+    }
+    catch(std::exception&)
+    {
+        result = EXIT_FAILURE;
+    }
 
     return result;
 }
diff --git a/src/site/markdown/extending.md b/src/site/markdown/extending.md
index c06e0389..1e826363 100644
--- a/src/site/markdown/extending.md
+++ b/src/site/markdown/extending.md
@@ -25,8 +25,7 @@ Sometimes, you may want to extend Log4cxx, for example by creating
 a new appender to write out data in a new format.  The following
 guide shows how you can extend Log4cxx in order to add a new appender.
 
-The full sample application can be found in the src/examples/cpp
-directory.
+The full sample application can be found at \ref custom-appender.cpp and \ref custom-appender.xml .
 
 The first thing for our example is to create a class that extends
 log4cxx.AppenderSkeleton so that we don't need to implement all of
@@ -139,3 +138,9 @@ to Log4cxx, including(but not limited to):
 * [Appenders](@ref log4cxx.Appender)
 * [Layouts](@ref log4cxx.Layout)
 * [Filters](@ref log4cxx.spi.Filter)
+
+\example custom-appender.cpp
+This example shows how to extend Log4cxx with a new appender.
+
+\example custom-appender.xml
+This example shows how to use a new appender in a configuration file.
diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md
index c376dcfb..14010d19 100644
--- a/src/site/markdown/usage.md
+++ b/src/site/markdown/usage.md
@@ -567,34 +567,15 @@ of Program Design 3*, edited by R. Martin, D. Riehle, and F. Buschmann
 (Addison-Wesley, 1997).
 
 To uniquely stamp each request, the user pushes contextual information
-into the NDC, the abbreviation of *Nested Diagnostic Context*. The NDC
-class is shown below.
-
-~~~{.cpp}
-    namespace log4cxx {
-    	class NDC {
-    		public:
-    			// pushes the value on construction and pops on destruction.
-    			NDC(const std::string& value);
-    			NDC(const std::wstring& value);
-
-    			// Remove the top of the context from the NDC.
-    			static LogString pop();
-
-    			// Add diagnostic context for the current thread.
-    			static void push(const std::string& message);
-    			static void push(const std::wstring& message);
-    	}
-    }
-~~~
+into the *Nested Diagnostic Context* (NDC) using the *log4cxx::NDC* class.
+For an example refer to \ref trivial.cpp.
+Note that all methods of the *log4cxx::NDC* class are static.
 
 The NDC is managed per thread as a *stack* of contextual information.
-Note that all methods of the *log4cxx::NDC* class are static. Assuming
-that NDC printing is turned on, every time a log request is made, the
-appropriate Log4cxx component will include the *entire* NDC stack for
-the current thread in the log output. This is done without the
-intervention of the user, who is responsible only for placing the
-correct information in the NDC by using the *push* and *pop* methods at
+Each log entry will include the entire stack
+for the current thread (for better control use *log4cxx::MDC*).
+The user is responsible for placing the correct information in the NDC
+by using the *push* and *pop* methods at
 a few well-defined points in the code. In contrast, the per-client
 logger approach commands extensive changes in the code.
 
@@ -799,6 +780,9 @@ and sent to different and multiple output targets in user-chosen
 formats. The Log4cxx package is designed so that log statements can
 remain in shipped code without incurring a heavy performance cost.
 
+\example trivial.cpp
+This example shows how to add a context string to each logging message using the NDC.
+
 \example auto-configured.cpp
 This is an example of logging in static initialization code and
 using the current module name to select the Log4cxx configuration file.