1 files changed, 12 insertions, 0 deletions
diff --git a/include/qpdf/QPDFPageDocumentHelper.hh b/include/qpdf/QPDFPageDocumentHelper.hh
index 6abe61e4..02c039b5 100644
--- a/include/qpdf/QPDFPageDocumentHelper.hh
+++ b/include/qpdf/QPDFPageDocumentHelper.hh
@@ -79,6 +79,18 @@ class QPDFPageDocumentHelper: public QPDFDocumentHelper
     // file. You could do this, for example, to convert a page into a
     // form XObject, though for that, you're better off using
     // QPDFPageObjectHelper::getFormXObjectForPage.
+    //
+    // This method does not have any specific awareness of annotations
+    // or form fields, so if you just add a page without thinking
+    // about it, you might end up with two pages that share form
+    // fields or annotations. While the page may look fine, it will
+    // probably not function properly with regard to interactive
+    // features. To work around this, you should called
+    // QPDFAcroFormDocumentHelper::fixCopiedAnnotations. A future
+    // version of qpdf will likely provide a higher-level interface
+    // for copying pages around that will handle document-level
+    // constructs in a less error-prone fashion.
+
     QPDF_DLL
     void addPage(QPDFPageObjectHelper newpage, bool first);