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/12/19 07:17:59 UTC
(logging-log4cxx) branch improve_macro_documentation created (now b71fe928)
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a change to branch improve_macro_documentation
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
at b71fe928 Improve documentation of macros by labelling example usage
This branch includes the following new commits:
new b71fe928 Improve documentation of macros by labelling example usage
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(logging-log4cxx) 01/01: Improve documentation of macros by labelling example usage
Posted by sw...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
swebb2066 pushed a commit to branch improve_macro_documentation
in repository https://gitbox.apache.org/repos/asf/logging-log4cxx.git
commit b71fe928880112980933799f5e0d2f43da44c7a8
Author: Stephen Webb <sw...@gmail.com>
AuthorDate: Tue Dec 19 18:07:31 2023 +1100
Improve documentation of macros by labelling example usage
---
src/main/include/log4cxx/logger.h | 100 +++++++++++++++++++++++---------------
src/site/doxy/Doxyfile.in | 2 +-
2 files changed, 63 insertions(+), 39 deletions(-)
diff --git a/src/main/include/log4cxx/logger.h b/src/main/include/log4cxx/logger.h
index 403e7c0e..07419bb4 100644
--- a/src/main/include/log4cxx/logger.h
+++ b/src/main/include/log4cxx/logger.h
@@ -2056,19 +2056,21 @@ Add a new logging event containing \c message to attached appender(s) if this lo
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>DEBUG</code> events.
-@param logger the logger that has the enabled status.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
LOG4CXX_DEBUG(m_log, "AddMesh:"
<< " name " << meshName
<< " type 0x" << std:: hex << traits.Type
<< " materialName " << meshObject.GetMaterialName()
- << " visible " << traits.IsDefaultVisible
+ << " visible? " << traits.IsDefaultVisible
<< " at " << obj->getBoundingBox().getCenter()
<< " +/- " << obj->getBoundingBox().getHalfSize()
);
~~~
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
+
*/
#define LOG4CXX_DEBUG(logger, message) do { \
if (LOG4CXX_UNLIKELY(::LOG4CXX_NS::Logger::isDebugEnabledFor(logger))) {\
@@ -2078,6 +2080,18 @@ LOG4CXX_DEBUG(m_log, "AddMesh:"
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>DEBUG</code> events.
+\usage
+~~~{.cpp}
+LOG4CXX_DEBUG(m_log, "AddMesh: name {} type 0x{x} materialName {} visible? {d} at {} +/- {}"
+ , meshName
+ , traits.Type
+ , meshObject.GetMaterialName()
+ , traits.IsDefaultVisible
+ , obj->getBoundingBox().getCenter()
+ , obj->getBoundingBox().getHalfSize()
+ );
+~~~
+
@param logger the logger to be used.
@param fmt the layout of the message.
@param ... the variable parts of the message.
@@ -2094,12 +2108,13 @@ Add a new logging event containing a message defined by \c fmt and <code>...</co
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>TRACE</code> events.
-@param logger the logger that has the enabled status.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
LOG4CXX_TRACE(m_log, "AddVertex:" << " at " << p << " n " << n << ' ' << color);
~~~
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
*/
#define LOG4CXX_TRACE(logger, message) do { \
if (LOG4CXX_UNLIKELY(::LOG4CXX_NS::Logger::isTraceEnabledFor(logger))) {\
@@ -2109,13 +2124,14 @@ Add a new logging event containing \c message to attached appender(s) if \c logg
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>TRACE</code> events.
-@param logger the logger to be used.
-@param fmt the layout of the message.
-@param ... the variable parts of the message.
-
+\usage
~~~{.cpp}
LOG4CXX_TRACE_FMT(m_log, "AddVertex: at {} n {} {}", p, n, color);
~~~
+
+@param logger the logger to be used.
+@param fmt the layout of the message.
+@param ... the variable parts of the message.
*/
#define LOG4CXX_TRACE_FMT(logger, fmt, ...) do { \
if (LOG4CXX_UNLIKELY(::LOG4CXX_NS::Logger::isTraceEnabledFor(logger))) {\
@@ -2129,9 +2145,7 @@ Add a new logging event containing a message defined by \c fmt and <code>...</co
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>INFO</code> events.
-@param logger the logger that has the enabled status.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
LOG4CXX_INFO(m_log, surface->GetName()
<< " successfully planned " << std::fixed << std::setprecision(1) << ((plannedArea / (plannedArea + unplannedArea)) * 100.0) << "%"
@@ -2140,6 +2154,9 @@ LOG4CXX_INFO(m_log, surface->GetName()
<< " planned segments " << surface->GetSegmentPlanCount() << " of " << surface->GetSegmentCount()
);
~~~
+
+@param logger the logger that has the enabled status.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
*/
#define LOG4CXX_INFO(logger, message) do { \
if (::LOG4CXX_NS::Logger::isInfoEnabledFor(logger)) {\
@@ -2149,10 +2166,7 @@ LOG4CXX_INFO(m_log, surface->GetName()
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>INFO</code> events.
-@param logger the logger to be used.
-@param fmt the layout of the message.
-@param ... the variable parts of the message.
-
+\usage
~~~{.cpp}
LOG4CXX_INFO_FMT(m_log, "{} successfully planned {:.1f}% planned area {:.4f}m^2 unplanned area {:.4f}m^2 planned segments {:d} of {:d}"
, surface->GetName(), (plannedArea / (plannedArea + unplannedArea)) * 100.0
@@ -2160,6 +2174,10 @@ LOG4CXX_INFO_FMT(m_log, "{} successfully planned {:.1f}% planned area {:.4f}m^2
, surface->GetSegmentPlanCount(), surface->GetSegmentCount()
);
~~~
+
+@param logger the logger to be used.
+@param fmt the layout of the message.
+@param ... the variable parts of the message.
*/
#define LOG4CXX_INFO_FMT(logger, fmt, ...) do { \
if (::LOG4CXX_NS::Logger::isInfoEnabledFor(logger)) {\
@@ -2173,15 +2191,16 @@ LOG4CXX_INFO_FMT(m_log, "{} successfully planned {:.1f}% planned area {:.4f}m^2
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>WARN</code> events.
-@param logger the logger to be used.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
catch (const std::exception& ex)
{
LOG4CXX_WARN(m_log, ex.what() << ": in " << m_task->GetParamFilePath());
}
~~~
+
+@param logger the logger to be used.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
*/
#define LOG4CXX_WARN(logger, message) do { \
if (::LOG4CXX_NS::Logger::isWarnEnabledFor(logger)) {\
@@ -2191,16 +2210,17 @@ catch (const std::exception& ex)
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>WARN</code> events.
-@param logger the logger to be used.
-@param fmt the layout of the message.
-@param ... the variable parts of the message.
-
+\usage
~~~{.cpp}
catch (const std::exception& ex)
{
LOG4CXX_WARN_FMT(m_log, "{}: in {}", ex.what(), m_task->GetParamFilePath());
}
~~~
+
+@param logger the logger to be used.
+@param fmt the layout of the message.
+@param ... the variable parts of the message.
*/
#define LOG4CXX_WARN_FMT(logger, fmt, ...) do { \
if (::LOG4CXX_NS::Logger::isWarnEnabledFor(logger)) {\
@@ -2214,15 +2234,16 @@ catch (const std::exception& ex)
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
-@param logger the logger to be used.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
catch (std::exception& ex)
{
LOG4CXX_ERROR(m_log, ex.what() << " in AddScanData");
}
~~~
+
+@param logger the logger to be used.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
*/
#define LOG4CXX_ERROR(logger, message) do { \
if (::LOG4CXX_NS::Logger::isErrorEnabledFor(logger)) {\
@@ -2232,16 +2253,17 @@ catch (std::exception& ex)
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>ERROR</code> events.
-@param logger the logger to be used.
-@param fmt the layout of the message.
-@param ... the variable parts of the message.
-
+\usage
~~~{.cpp}
catch (std::exception& ex)
{
LOG4CXX_ERROR_FMT(m_log, "{} in AddScanData", ex.what());
}
~~~
+
+@param logger the logger to be used.
+@param fmt the layout of the message.
+@param ... the variable parts of the message.
*/
#define LOG4CXX_ERROR_FMT(logger, fmt, ...) do { \
if (::LOG4CXX_NS::Logger::isErrorEnabledFor(logger)) {\
@@ -2286,12 +2308,13 @@ if \c logger is enabled for <code>ERROR</code> events.
/**
Add a new logging event containing \c message to attached appender(s) if \c logger is enabled for <code>FATAL</code> events.
-@param logger the logger to be used.
-@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
-
+\usage
~~~{.cpp}
LOG4CXX_FATAL(m_log, m_renderSystem->getName() << " is not supported");
~~~
+
+@param logger the logger to be used.
+@param message a valid r-value expression of an <code>operator<<(std::ostream&. ...)</code> overload.
*/
#define LOG4CXX_FATAL(logger, message) do { \
if (::LOG4CXX_NS::Logger::isFatalEnabledFor(logger)) {\
@@ -2301,13 +2324,14 @@ LOG4CXX_FATAL(m_log, m_renderSystem->getName() << " is not supported");
/**
Add a new logging event containing a message defined by \c fmt and <code>...</code> to attached appender(s) if \c logger is enabled for <code>FATAL</code> events.
+\usage
+~~~{.cpp}
+LOG4CXX_FATAL_FMT(m_log, "{} is not supported", m_renderSystem->getName());
+~~~
@param logger the logger to be used.
@param fmt the layout of the message.
@param ... the variable parts of the message.
-~~~{.cpp}
-LOG4CXX_FATAL_FMT(m_log, "{} is not supported", m_renderSystem->getName());
-~~~
*/
#define LOG4CXX_FATAL_FMT(logger, fmt, ...) do { \
if (::LOG4CXX_NS::Logger::isFatalEnabledFor(logger)) {\
diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in
index 574d0920..8f5b5b4a 100644
--- a/src/site/doxy/Doxyfile.in
+++ b/src/site/doxy/Doxyfile.in
@@ -298,7 +298,7 @@ TAB_SIZE = 4
# with the commands \{ and \} for these it is advised to use the version @{ and
# @} or use a double escape (\\{ and \\})
-ALIASES =
+ALIASES = usage="\par Example usage:^^"
# 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