DOC: Tweak some comments (#3242)

Author: j-t-1

pypdf/_doc_common.py

@@ -391,20 +391,18 @@ def recursive_call(
             if node["/Type"] == "/Page":
                 if page_number == mi:
                     return node, -1
-                # else
                 return None, mi + 1
             if (page_number - mi) >= ma:  # not in nodes below
                 if node == top:
                     return top, -1
-                # else
                 return None, mi + ma
             for idx, kid in enumerate(cast(ArrayObject, node["/Kids"])):
                 kid = cast(DictionaryObject, kid.get_object())
                 n, i = recursive_call(kid, mi)
                 if n is not None:  # page has just been found ...
                     if i < 0:  # ... just below!
                         return node, idx
-                    # else:  # ... at lower levels
+                    # ... at lower levels
                     return n, i
                 mi = i
             raise PyPdfError("Unexpectedly cannot find the node.")
@@ -429,7 +427,7 @@ def get_named_dest_root(self) -> ArrayObject:
             names = cast(DictionaryObject, self.root_object[CA.NAMES])
             names_ref = names.indirect_reference
             if CA.DESTS in names and isinstance(names[CA.DESTS], DictionaryObject):
-                # 3.6.3 Name Dictionary (PDF spec 1.7)
+                # §3.6.3 Name Dictionary (PDF spec 1.7)
                 dests = cast(DictionaryObject, names[CA.DESTS])
                 dests_ref = dests.indirect_reference
                 if CA.NAMES in dests:
@@ -527,8 +525,8 @@ def _get_named_destinations(
                     retval[k__] = dest
         return retval
 
-    # A select group of relevant field attributes. For the complete list.
-    # See §12.3.2 of the PDF 1.7 or PDF 2.0 specification.
+    # A select group of relevant field attributes. For the complete list,
+    # see §12.3.2 of the PDF 1.7 or PDF 2.0 specification.
 
     def get_fields(
         self,
@@ -669,7 +667,7 @@ def _write_field(self, fileobj: Any, field: Any, field_attributes: Any) -> None:
             attr_name = field_attributes[attr]
             try:
                 if attr == FA.FT:
-                    # Make the field type value more clear
+                    # Make the field type value clearer
                     types = {
                         "/Btn": "Button",
                         "/Tx": "Text",
@@ -971,7 +969,7 @@ def _build_outline_item(self, node: DictionaryObject) -> Optional[Destination]:
         dest, title, outline_item = None, None, None
 
         # title required for valid outline
-        # § 12.3.3, entries in an outline item dictionary
+        # §12.3.3, entries in an outline item dictionary
         try:
             title = cast("str", node["/Title"])
         except KeyError:

pypdf/_text_extraction/_layout_mode/_font.py

@@ -38,7 +38,7 @@ class Font:
     def __post_init__(self) -> None:
         # Type3 fonts that do not specify a "/ToUnicode" mapping cannot be
         # reliably converted into character codes unless all named chars
-        # in /CharProcs map to a standard adobe glyph. See § 9.10.2 of the
+        # in /CharProcs map to a standard adobe glyph. See §9.10.2 of the
         # PDF 1.7 standard.
         if self.subtype == "/Type3" and "/ToUnicode" not in self.font_dictionary:
             self.interpretable = all(

pypdf/_writer.py

@@ -158,12 +158,11 @@ class PdfWriter(PdfDocCommon):
 
         incremental: If true, loads the document and set the PdfWriter in incremental mode.
 
-
             When writing incrementally, the original document is written first and new/modified
             content is appended. To be used for signed document/forms to keep signature valid.
 
         full: If true, loads all the objects (always full if incremental = True).
-            This parameters may allows to load very big PDFs.
+            This parameter may allow loading large PDFs.
 
     """
 
@@ -220,7 +219,7 @@ def __init__(
                 raise PyPdfError("Invalid type for incremental mode")
             self._reader = fileobj  # prev content is in _reader.stream
             self._header = fileobj.pdf_header.encode()
-            self._readonly = True  # !!!TODO: to be analysed
+            self._readonly = True  # TODO: to be analysed
         else:
             self._header = b"%PDF-1.3"
             self._info_obj = self._add_object(
@@ -253,12 +252,12 @@ def _get_clone_from(
             return clone_from
 
         clone_from = _get_clone_from(fileobj, clone_from)
-        # to prevent overwriting
+        # To prevent overwriting
         self.temp_fileobj = fileobj
         self.fileobj = ""
         self._with_as_usage = False
         self._cloned = False
-        # The root of our page tree node.
+        # The root of our page tree node
         pages = DictionaryObject()
         pages.update(
             {
@@ -614,7 +613,7 @@ def _get_page_number_by_indirect(
             The page number or None
 
         """
-        # to provide same function as in PdfReader
+        # To provide same function as in PdfReader
         if is_null_or_none(indirect_reference):
             return None
         assert indirect_reference is not None, "mypy"
@@ -1572,7 +1571,7 @@ def metadata(self) -> Optional[DocumentInformation]:
 
         Note that some PDF files use (XMP) metadata streams instead of document
         information dictionaries, and these metadata streams will not be
-        accessed by this function.
+        accessed by this function, but by :meth:`~xmp_metadata`.
 
         """
         return super().metadata
@@ -2658,7 +2657,7 @@ def append(
                 import_outline,
                 excluded_fields,
             )
-        else:  # if isinstance(outline_item,str):
+        else:  # if isinstance(outline_item, str):
             self.merge(
                 None,
                 fileobj,

pypdf/xmp.py

@@ -323,7 +323,7 @@ def _get_text(self, element: XmlElement) -> str:
     """The PDF file version, for example 1.0 or 1.3."""
 
     pdf_producer = property(_getter_single(PDF_NAMESPACE, "Producer"))
-    """The name of the tool that created the PDF document."""
+    """The name of the tool that saved the document as a PDF."""
 
     xmp_create_date = property(
         _getter_single(XMP_NAMESPACE, "CreateDate", _converter_date)