Explain how CPDF_Object works
Add comments in cpdf_object.h to explain how a PDF object, as seen
inside the PDF itself, maps to CPDF_Object instances.
Change-Id: Id1fb5c1cfa9211fc6935ca3fedd884d089d0b711
Reviewed-on: https://pdfium-review.googlesource.com/c/pdfium/+/105571
Auto-Submit: Lei Zhang <thestig@chromium.org>
Reviewed-by: Tom Sepez <tsepez@chromium.org>
Commit-Queue: Tom Sepez <tsepez@chromium.org>
diff --git a/core/fpdfapi/parser/cpdf_object.h b/core/fpdfapi/parser/cpdf_object.h
index 1128f69..4793b61 100644
--- a/core/fpdfapi/parser/cpdf_object.h
+++ b/core/fpdfapi/parser/cpdf_object.h
@@ -28,6 +28,25 @@
class CPDF_String;
class IFX_ArchiveStream;
+// ISO 32000-1:2008 defines PDF objects. When CPDF_Parser parses a PDF object,
+// it represents the PDF object using CPDF_Objects. Take this PDF object for
+// example:
+//
+// 4 0 obj <<
+// /Type /Pages
+// /Count 1
+// /Kids [9 0 R]
+// >>
+//
+// Multiple CPDF_Objects instances are necessary to represent this PDF object:
+// 1) A CPDF_Dictionary with object number 4 that contains 3 elements.
+// 2) A CPDF_Name for /Pages.
+// 3) A CPDF_Number for the count of 1.
+// 4) A CPDF_Array for [9 0 R], which contains 1 element.
+// 5) A CPDF_Reference that references object 9 0.
+//
+// CPDF_Object (1) has an object number of 4. All the other CPDF_Objects are
+// inline objects. CPDF_Object represent that by using an object number of 0.
class CPDF_Object : public Retainable {
public:
static constexpr uint32_t kInvalidObjNum = static_cast<uint32_t>(-1);
