[logging-log4cxx] branch master updated: Updated documentation about shared_ptrs

[rm...@apache.org]

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

rmiddleton 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 70199c5  Updated documentation about shared_ptrs
70199c5 is described below

commit 70199c597ee02f5582dcfee47b8947d7c4abaa33
Author: Robert Middleton <ro...@rm5248.com>
AuthorDate: Mon Apr 26 21:04:39 2021 -0400

    Updated documentation about shared_ptrs
---
 src/main/include/log4cxx/helpers/object.h |  6 ++++++
 src/site/doxy/Doxyfile.in                 |  2 +-
 src/site/markdown/change-report-gh.md     | 26 ++++++++++++++++++++++++++
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/src/main/include/log4cxx/helpers/object.h b/src/main/include/log4cxx/helpers/object.h
index b945bbf..18b6728 100644
--- a/src/main/include/log4cxx/helpers/object.h
+++ b/src/main/include/log4cxx/helpers/object.h
@@ -109,6 +109,12 @@ class LOG4CXX_EXPORT Object
 LOG4CXX_PTR_DEF(Object);
 }
 
+/**
+ * Attempt to cast one Object to another kind of Object.
+ *
+ * On success, returns a new shared pointer that points at incoming.
+ * On failure, returns an invalid shared pointer.
+ */
 template<typename Ret,
 	typename Type,
 	bool = std::is_base_of<Ret, helpers::Object>::value,
diff --git a/src/site/doxy/Doxyfile.in b/src/site/doxy/Doxyfile.in
index fa53335..d0e3933 100644
--- a/src/site/doxy/Doxyfile.in
+++ b/src/site/doxy/Doxyfile.in
@@ -450,7 +450,7 @@ LOOKUP_CACHE_SIZE      = 0
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
diff --git a/src/site/markdown/change-report-gh.md b/src/site/markdown/change-report-gh.md
index 9f032af..29a7bc2 100644
--- a/src/site/markdown/change-report-gh.md
+++ b/src/site/markdown/change-report-gh.md
@@ -48,6 +48,27 @@ are now created using `std::shared_ptr` as the smart pointer implementation.
 
 Alternative build systems have been removed, and we now support CMake only for building the library.
 
+With the introduction of smart pointers, the old behavior of implicit casting no longer works.  In
+order to cast between classes, use the new [log4cxx::cast](@ref log4cxx.cast) method.  This method returns an invalid
+`shared_ptr` on failure, or a `shared_ptr` pointing at the same object on success.  This should be
+transparent to user code, unless you are interacting with log4cxx internals directly.
+
+Before:
+
+```{.cpp}
+ObjectPtr instance = Loader::loadClass(className).newInstance();
+AppenderPtr appender = instance;
+```
+
+After:
+
+```{.cpp}
+ObjectPtr instance = ObjectPtr(Loader::loadClass(className).newInstance());
+AppenderPtr appender = log4cxx::cast<Appender>(instance);
+// At this point(assuming the cast was good), instance and appender
+// both point at the same object.
+```
+
 Bug
 ---
 
@@ -74,6 +95,11 @@ New Feature
 -   \[[LOGCXX-515](https://issues.apache.org/jira/browse/LOGCXX-515)\] -
     Add macros to utilize libfmt formatting for messages
 
+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