[lmi-commits] [lmi] master 783f4dd 5/9: Consolidate and revise documentation

[Greg Chicares]

branch: master
commit 783f4dd835466ada15c6ff38c934ae605639f26a
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Consolidate and revise documentation
    
    It seems generally best to comment a member function in one place only:
    at its point of definition. This particular comment should be included
    in documentation generated with a tool such as doxygen, so it's written
    as a '///' block, with one blank line following, immediately preceding
    the function definition.
    
    The content of the original is preserved except for one deliberate
    change: if the canonical
      ctor: N = std::uncaught_exceptions();
      dtor: if(N != std::uncaught_exceptions())
    idiom had been used, and N had been 1 in both the ctor and the dtor,
    then the dtor wouldn't omit a desirable though noncritical diagnostic:
    instead, it would emit an unintended diagnostic.
    
    It is arguable whether it would be simpler to follow that canonical
    idiom rather than expending a larger number of characters in a comment
    explaining why it wasn't followed.
---
 pdf_writer_wx.cpp | 17 ++++++++++-------
 pdf_writer_wx.hpp |  1 -
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/pdf_writer_wx.cpp b/pdf_writer_wx.cpp
index ffff225..27c6859 100644
--- a/pdf_writer_wx.cpp
+++ b/pdf_writer_wx.cpp
@@ -260,15 +260,18 @@ void pdf_writer_wx::save() &&
     save_has_been_called_ = true;
 }
 
+/// Dtor: validates that save() has been called.
+///
+/// Canonically, std::uncaught_exceptions() would be called in each
+/// ctor, and its result there compared to its result here. Instead,
+/// for simplicity it's called only here--in effect, presuming that
+/// no object of this class is created by another object's dtor. At
+/// worst, this simplification would result in displaying a warning
+/// that wouldn't otherwise be shown, in a situation so weird that
+/// a warning would be appropriate.
+
 pdf_writer_wx::~pdf_writer_wx()
 {
-    // We keep things simple and just check whether any exceptions are
-    // currently in progress instead of storing the number of exceptions being
-    // handled in ctor and checking if this number is greater here, because it
-    // seems highly unlikely that a pdf_writer_wx object would ever be created
-    // in a dtor of some other object, which is the only situation in which the
-    // two versions would behave differently -- and even if it did happen, it
-    // would just result in incorrectly skipping the check, i.e. not critical.
     if(!std::uncaught_exceptions() && !save_has_been_called_)
         {
         safely_show_message("Please report this: save() not called for PDF.");
diff --git a/pdf_writer_wx.hpp b/pdf_writer_wx.hpp
index 9a1835e..826120d 100644
--- a/pdf_writer_wx.hpp
+++ b/pdf_writer_wx.hpp
@@ -52,7 +52,6 @@ class pdf_writer_wx
     pdf_writer_wx(pdf_writer_wx const&) = delete;
     pdf_writer_wx& operator=(pdf_writer_wx const&) = delete;
 
-    // Dtor checks if save() had been called, so don't forget to do it.
     ~pdf_writer_wx();
 
     // Save the PDF to the output file name specified in the ctor.