document.rb in hexapdf-0.13.0

- old
+ new

@@ -67,19 +67,39 @@
 # * HexaPDF::Content::Canvas provides the canvas API for drawing/writing on a page or form XObject
 module HexaPDF
 
   autoload(:Composer, 'hexapdf/composer')
 
+  # == HexaPDF::Document
+  #
   # Represents one PDF document.
   #
   # A PDF document consists of (indirect) objects, so the main job of this class is to provide
   # methods for working with these objects. However, since a PDF document may also be
   # incrementally updated and can therefore contain one or more revisions, there are also methods
-  # to work with these revisions.
+  # for working with these revisions.
   #
   # Note: This class provides everything to work on PDF documents on a low-level basis. This means
-  # that there are no convenience methods for higher PDF functionality whatsoever.
+  # that there are no convenience methods for higher PDF functionality. Those can be found in the
+  # objects linked from here, like #catalog.
+  #
+  # == Known Messages
+  #
+  # The document object provides a basic message dispatch system via #register_listener and
+  # #dispatch_message.
+  #
+  # Following are the messages that are used by HexaPDF itself:
+  #
+  # :complete_objects::
+  #      This message is called before the first step of writing a document. Listeners should
+  #      complete PDF objects that are missing some information.
+  #
+  #      For example, the font system uses this message to complete the font objects with
+  #      information that is only available once all the used glyphs are known.
+  #
+  # :before_write::
+  #      This message is called before a document is actually serialized and written.
   class Document
 
     autoload(:Pages, 'hexapdf/document/pages')
     autoload(:Fonts, 'hexapdf/document/fonts')
     autoload(:Images, 'hexapdf/document/images')
@@ -398,15 +418,15 @@
     #
     # Calls the given block once for every object, or, if +only_loaded+ is +true+, for every loaded
     # object in the PDF document. The block may either accept only the object or the object and the
     # revision it is in.
     #
-    # By default, only the current version of each object is returned which implies that each
-    # object number is yielded exactly once. If the +current+ option is +false+, all stored
-    # objects from newest to oldest are returned, not only the current version of each object.
+    # By default, only the current version of each object is returned which implies that each object
+    # number is yielded exactly once. If the +only_current+ option is +false+, all stored objects
+    # from newest to oldest are returned, not only the current version of each object.
     #
-    # The +current+ option can make a difference because the document can contain multiple
+    # The +only_current+ option can make a difference because the document can contain multiple
     # revisions:
     #
     # * Multiple revisions may contain objects with the same object and generation numbers, e.g.
     #   two (different) objects with oid/gen [3,0].
     #
@@ -440,10 +460,13 @@
       (@listeners[name] ||= []) << callable
       callable
     end
 
     # Dispatches the message +name+ with the given arguments to all registered listeners.
+    #
+    # See the main Document documentation for an overview of messages that are used by HexaPDF
+    # itself.
     def dispatch_message(name, *args)
       @listeners[name]&.each {|obj| obj.call(*args) }
     end
 
     # Caches the value or the return value of the given block using the given Object::PDFData and
@@ -592,17 +615,13 @@
     # auto-correction, and returns +true+ if everything is fine.
     #
     # If a block is given, it is called on validation problems.
     #
     # See HexaPDF::Object#validate for more information.
-    def validate(auto_correct: true, only_loaded: false) #:yield: object, msg, correctable
-      cur_obj = trailer
-      block = (block_given? ? lambda {|msg, correctable| yield(cur_obj, msg, correctable) } : nil)
-
+    def validate(auto_correct: true, only_loaded: false, &block) #:yield: msg, correctable, object
       result = trailer.validate(auto_correct: auto_correct, &block)
       each(only_current: false, only_loaded: only_loaded) do |obj|
-        cur_obj = obj
         result &&= obj.validate(auto_correct: auto_correct, &block)
       end
       result
     end
 
@@ -641,10 +660,10 @@
         trailer.update_id
         trailer.info[:ModDate] = Time.now
       end
 
       if validate
-        self.validate(auto_correct: true) do |obj, msg, correctable|
+        self.validate(auto_correct: true) do |msg, correctable, obj|
           next if correctable
           raise HexaPDF::Error, "Validation error for (#{obj.oid},#{obj.gen}): #{msg}"
         end
       end
 