Slightly improve the docs and make more debug data available in test

apolukhin · apolukhin · commit a9d92be86ab6 · 2017-07-17T22:44:56.000+03:00
diff --git a/example/terminate_handler.cpp b/example/terminate_handler.cpp
@@ -199,15 +199,15 @@ int test_inplace() {
     const bool is_noop = !boost::stacktrace::stacktrace();
 
     {
-        boost::stacktrace::safe_dump_to("./backtrace2.dump"); 
+        const std::size_t frames_ss1 = boost::stacktrace::safe_dump_to("./backtrace2.dump");
         boost::stacktrace::stacktrace ss2;
         std::ifstream ifs("./backtrace2.dump");
         boost::stacktrace::stacktrace ss1 = boost::stacktrace::stacktrace::from_dump(ifs);
         ifs.close();
         boost::filesystem::remove("./backtrace2.dump");
 
-        if (ss1.size() != ss2.size()) {
-            std::cerr << "Stacktraces differ:\n" << ss1 << "\n vs \n" << ss2 << '\n';
+        if (ss2.size() != ss1.size()) {
+            std::cerr << "Stacktraces differ. Dumped size == " << frames_ss1 << ".\n" << ss1 << "\n vs \n" << ss2 << '\n';
             return 51;
         }
 
@@ -224,12 +224,12 @@ int test_inplace() {
 
     {
         void* data[1024];
-        boost::stacktrace::safe_dump_to(data, sizeof(data));
+        const std::size_t frames_ss1 = boost::stacktrace::safe_dump_to(data, sizeof(data));
         boost::stacktrace::stacktrace ss2;
         boost::stacktrace::stacktrace ss1 = boost::stacktrace::stacktrace::from_dump(data, sizeof(data));
 
-        if (ss1.size() != ss2.size()) {
-            std::cerr << "Stacktraces differ:\n" << ss1 << "\n vs \n" << ss2 << '\n';
+        if (ss1.size() + 1 != frames_ss1 || ss1.size() != ss2.size()) {
+            std::cerr << "Stacktraces differ. Dumped size == " << frames_ss1 << ".\n" << ss1 << "\n vs \n" << ss2 << '\n';
             return 53;
         }
 
diff --git a/include/boost/stacktrace/safe_dump_to.hpp b/include/boost/stacktrace/safe_dump_to.hpp
@@ -76,7 +76,7 @@ struct this_thread_frames { // struct is required to avoid warning about usage o
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param memory Preallocated buffer to store current function call sequence into.
 ///
@@ -91,7 +91,7 @@ BOOST_FORCEINLINE std::size_t safe_dump_to(void* memory, std::size_t size) BOOST
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param skip How many top calls to skip and do not store.
 ///
@@ -109,7 +109,7 @@ BOOST_FORCEINLINE std::size_t safe_dump_to(std::size_t skip, void* memory, std::
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param file File to store current function call sequence.
 BOOST_FORCEINLINE std::size_t safe_dump_to(const char* file) BOOST_NOEXCEPT {
@@ -122,7 +122,7 @@ BOOST_FORCEINLINE std::size_t safe_dump_to(const char* file) BOOST_NOEXCEPT {
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param skip How many top calls to skip and do not store.
 ///
@@ -141,7 +141,7 @@ BOOST_FORCEINLINE std::size_t safe_dump_to(std::size_t skip, std::size_t max_dep
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param file File to store current function call sequence.
 BOOST_FORCEINLINE std::size_t safe_dump_to(platform_specific_descriptor fd) BOOST_NOEXCEPT;
@@ -152,7 +152,7 @@ BOOST_FORCEINLINE std::size_t safe_dump_to(platform_specific_descriptor fd) BOOS
 ///
 /// @b Async-Handler-Safety: Safe.
 ///
-/// @returns Stored call sequence depth.
+/// @returns Stored call sequence depth including terminating zero frame.
 ///
 /// @param skip How many top calls to skip and do not store.
 ///
diff --git a/include/boost/stacktrace/stacktrace.hpp b/include/boost/stacktrace/stacktrace.hpp
@@ -288,7 +288,7 @@ class basic_stacktrace {
         return impl_;
     }
 
-    /// Constructs stacktrace from basic_istreamable that references the dumped stacktrace.
+    /// Constructs stacktrace from basic_istreamable that references the dumped stacktrace. Terminating zero frame is discarded.
     ///
     /// @b Complexity: O(N)
     template <class Char, class Trait>
@@ -319,13 +319,13 @@ class basic_stacktrace {
         return ret;
     }
 
-    /// Constructs stacktrace from raw memory dump.
+    /// Constructs stacktrace from raw memory dump. Terminating zero frame is discarded.
     ///
     /// @b Complexity: O(size) in worst case
-    static basic_stacktrace from_dump(const void* begin, std::size_t size, const allocator_type& a = allocator_type()) {
+    static basic_stacktrace from_dump(const void* begin, std::size_t buffer_size_in_bytes, const allocator_type& a = allocator_type()) {
         basic_stacktrace ret(0, 0, a);
         const native_frame_ptr_t* first = static_cast<const native_frame_ptr_t*>(begin);
-        const std::size_t frames_count = frames_count_from_buffer_size(size);
+        const std::size_t frames_count = frames_count_from_buffer_size(buffer_size_in_bytes);
         if (!frames_count) {
             return ret;
         }
