Add additional comments about new accessor methods

Jay Berkenbilt
1 parent fa0b6384
Showing 3 changed files with 29 additions and 8 deletions
include/qpdf/QPDFObjectHandle.hh
manual/design.rst
manual/release-notes.rst
@@ -657,13 +657,25 @@ class QPDFObjectHandle
     //
     // In PDF files, objects have specific types, but there is nothing
     // that prevents PDF files from containing objects of types that
-    // aren't expected by the specification. Many of the accessors
-    // here expect objects of a particular type. Prior to qpdf 8,
-    // calling an accessor on a method of the wrong type, such as
-    // trying to get a dictionary key from an array, trying to get the
-    // string value of a number, etc., would throw an exception, but
-    // since qpdf 8, qpdf issues a warning and recovers using the
-    // following behavior:
+    // aren't expected by the specification.
+    //
+    // There are two flavors of accessor methods:
+    //
+    // * getSomethingValue() returns the value and issues a type
+    //   warning if the type is incorrect.
+    //
+    // * getValueAsSomething() returns false if the value is the wrong
+    //   type. Otherwise, it returns true and initializes a reference
+    //   of the appropriate type. These methods never issue type
+    //   warnings.
+    //
+    // The getSomethingValue() accessors and some of the other methods
+    // expect objects of a particular type. Prior to qpdf 8, calling
+    // an accessor on a method of the wrong type, such as trying to
+    // get a dictionary key from an array, trying to get the string
+    // value of a number, etc., would throw an exception, but since
+    // qpdf 8, qpdf issues a warning and recovers using the following
+    // behavior:
     //
     // * Requesting a value of the wrong type (int value from string,
     //   array item from a scalar or dictionary, etc.) will return a
@@ -746,6 +746,15 @@ and set return values in passed-in pointers, but this would complicate
 both the implementation and the use of the library for a case that is
 actually quite rare and largely avoidable.
+*How can I avoid type warnings altogether?* For each
+``getSomethingValue`` accessor that returns a value of the requested
+type and issues a warning for objects of the wrong type, there is also
+a ``getValueAsSomething`` method (since qpdf 10.6) that returns false
+for objects of the wrong type and otherwise returns true and
+initializes a reference. These methods never generate type warnings
+and provide an alternative to explicitly checking the type of an
+object before calling an accessor method.
+
 .. _smart-pointers:
 Smart Pointers
@@ -99,7 +99,7 @@ For a detailed list of changes, please see the file
       - The newer accessor methods return a boolean indicating whether
         or not the object is of the expected type. If it is, a
-        reference of the correct type is returned.
+        reference to a variable of the correct type is initialized.
       In many cases, the new interfaces will enable more compact code
       and will also never generate type warnings. Thanks to M. Holger