document.rb in hexapdf-0.44.0

- old
+ new

@@ -276,10 +276,18 @@
     # object.
     #
     # If the same argument is provided in multiple invocations, the import is done only once and
     # the previously imported object is returned.
     #
+    # Note: If you first create a PDF document from scratch and then want to import objects from it
+    # into another PDF document, you need to run the following on the source document:
+    #
+    #   doc.dispatch_message(:complete_objects)
+    #   doc.validate
+    #
+    # This ensures that the source document has all the necessary PDF structures set-up correctly.
+    #
     # See: Importer
     def import(obj)
       source = (obj.kind_of?(HexaPDF::Object) ? obj.document : nil)
       HexaPDF::Importer.for(self).import(obj, source: source)
     end
@@ -615,16 +623,21 @@
     # Encryption is done by setting up a security handler for this purpose and populating the
     # trailer's Encrypt dictionary accordingly. The actual encryption, however, is only done when
     # writing the document.
     #
     # The security handler used for encrypting is selected via the +name+ argument. All other
-    # arguments are passed on the security handler.
+    # arguments are passed on to the security handler.
     #
     # If the document should not be encrypted, the +name+ argument has to be set to +nil+. This
     # removes the security handler and deletes the trailer's Encrypt dictionary.
     #
     # See: Encryption::SecurityHandler#set_up_encryption and
     # Encryption::StandardSecurityHandler::EncryptionOptions for possible encryption options.
+    #
+    # Examples:
+    #
+    #   document.encrypt(name: nil)  # remove the existing encryption
+    #   document.encrypt(algorithm: :aes, key_length: 256, permissions: [:print, :extract_content]
     def encrypt(name: :Standard, **options)
       if name.nil?
         trailer.delete(:Encrypt)
         @security_handler = nil
       else