[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[lmi-commits] [lmi] master 783f4dd 5/9: Consolidate and revise documenta
[lmi-commits] [lmi] master 783f4dd 5/9: Consolidate and revise documentation
Wed, 4 Apr 2018 21:27:37 -0400 (EDT)
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
@@ -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.
- // 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
@@ -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.
// Save the PDF to the output file name specified in the ctor.
- [lmi-commits] [lmi] master updated (d9f9215 -> f4580cf), Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master 035e5a0 2/9: Simplify, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master afdbbeb 6/9: Consolidate commentary, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master 38df10a 4/9: Simplify diagnostics, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master 6586cab 1/9: Simplify, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master ecd1362 3/9: Shorten diagnostics, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master 783f4dd 5/9: Consolidate and revise documentation,
Greg Chicares <=
- [lmi-commits] [lmi] master f4580cf 9/9: Don't ref-qualify save(), Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master 5d225f5 7/9: Move commentary to point of member-function definition, Greg Chicares, 2018/04/04
- [lmi-commits] [lmi] master f5651d1 8/9: Prevent save() from being called twice, Greg Chicares, 2018/04/04