DOC: Slightly improve the wording of PageObject (#2625)

* DOC: Slightly improve the wording of PageObject

Also make metadata examples more concise

* DOC: Slightly improve the wording of PageObject

Also make metadata examples more concise

---------

Co-authored-by: Stefan <96178532+stefan6419846@users.noreply.github.com>

docs/user/metadata.md

@@ -9,8 +9,6 @@ reader = PdfReader("example.pdf")
 
 meta = reader.metadata
 
-print(len(reader.pages))
-
 # All of the following could be None!
 print(meta.title)
 print(meta.author)
@@ -34,9 +32,9 @@ writer = PdfWriter()
 for page in reader.pages:
     writer.add_page(page)
 
-# If you want to add the old metadata, include this line
-metadata = reader.metadata
-writer.add_metadata(metadata)
+# If you want to add the old metadata, include these two lines
+if reader.metadata is not None:
+    writer.add_metadata(reader.metadata)
 
 # Format the current date and time for the metadata
 utc_time = "-05'00'"  # UTC time optional

pypdf/_page.py

@@ -367,7 +367,7 @@ def create_blank_page(
         from the last page of *pdf*.
 
         Args:
-            pdf: PDF file the page belongs to
+            pdf: PDF file the page is within.
             width: The width of the new page expressed in default user
                 space units.
             height: The height of the new page expressed in default user
@@ -651,7 +651,7 @@ def _get_inline_images(self) -> Dict[str, ImageFile]:
     @property
     def rotation(self) -> int:
         """
-        The VISUAL rotation of the page.
+        The visual rotation of the page.
 
         This number has to be a multiple of 90 degrees: 0, 90, 180, or 270 are
         valid values. This property does not affect ``/Contents``.
@@ -668,7 +668,7 @@ def transfer_rotation_to_content(self) -> None:
         Apply the rotation of the page to the content and the media/crop/...
         boxes.
 
-        It's recommended to apply this function before page merging.
+        It is recommended to apply this function before page merging.
         """
         r = -self.rotation  # rotation to apply is in the otherway
         self.rotation = 0
@@ -862,8 +862,8 @@ def get_contents(self) -> Optional[ContentStream]:
         Access the page contents.
 
         Returns:
-            The ``/Contents`` object, or ``None`` if it doesn't exist.
-            ``/Contents`` is optional, as described in PDF Reference  7.7.3.3
+            The ``/Contents`` object, or ``None`` if it does not exist.
+            ``/Contents`` is optional, as described in §7.7.3.3 of the PDF Reference.
         """
         if PG.CONTENTS in self:
             try:
@@ -884,7 +884,7 @@ def replace_contents(
         """
         Replace the page contents with the new content and nullify old objects
         Args:
-            content : new content. if None delete the content field.
+            content : new content; if None delete the content field.
         """
         if not hasattr(self, "indirect_reference") or self.indirect_reference is None:
             # the page is not attached : the content is directly attached.
@@ -1077,7 +1077,7 @@ def _merge_page_writer(
         expand: bool = False,
     ) -> None:
         # First we work on merging the resource dictionaries.  This allows us
-        # to find out what symbols in the content streams we might need to
+        # to find which symbols in the content streams we might need to
         # rename.
         assert isinstance(self.indirect_reference, IndirectObject)
         pdf = self.indirect_reference.pdf
@@ -1496,10 +1496,10 @@ def compress_content_streams(self, level: int = -1) -> None:
     @property
     def page_number(self) -> Optional[int]:
         """
-        Read-only property which return the page number with the pdf file.
+        Read-only property which return the page number within the PDF file.
 
         Returns:
-            int : page number ; None if the page is not attached to a pdf
+            int : page number; None if the page is not attached to a PDF
         """
         if self.indirect_reference is None:
             return None
@@ -1995,7 +1995,7 @@ def extract_text(
         Do not rely on the order of text coming out of this function, as it
         will change if this function is made more sophisticated.
 
-        Arabic, Hebrew,... are extracted in the good order.
+        Arabic and Hebrew are extracted in the correct order.
         If required an custom RTL range of characters can be defined;
         see function set_custom_rtl
 
@@ -2004,10 +2004,10 @@ def extract_text(
         For example in some PDF files this can be useful to parse tables.
 
         Args:
-            orientations: list of orientations text_extraction will look for
+            orientations: list of orientations extract_text will look for
                 default = (0, 90, 180, 270)
-                note: currently only 0(Up),90(turned Left), 180(upside Down),
-                270 (turned Right)
+                note: currently only 0 (up),90 (turned left), 180 (upside down),
+                270 (turned right)
             space_width: force default space width
                 if not extracted from font (default: 200)
             visitor_operand_before: function to be called before processing an operation.
@@ -2026,7 +2026,7 @@ def extract_text(
                 NOTE: orientations, space_width, and visitor_* parameters are NOT respected
                 in "layout" mode.
 
-        KwArgs:
+        kwargs:
             layout_mode_space_vertically (bool): include blank lines inferred from
                 y distance + font height. Defaults to True.
             layout_mode_scale_weight (float): multiplier for string length when calculating
@@ -2184,8 +2184,8 @@ def annotations(self, value: Optional[ArrayObject]) -> None:
         """
         Set the annotations array of the page.
 
-        Typically you don't want to set this value, but append to it.
-        If you append to it, don't forget to add the object first to the writer
+        Typically you do not want to set this value, but append to it.
+        If you append to it, remember to add the object first to the writer
         and only add the indirect object.
         """
         if value is None: