DOC: Update references and formatting (#2529)

Author: j-t-1

docs/meta/faq.md

@@ -48,7 +48,7 @@ In BibTeX format:
                   Martin Thoma and
                   Matthew Peveler and
                   exiledkingcc and {pypdf Contributors}},
- year          = {2022},
+ year          = {2024},
  url           = {https://pypi.org/project/pypdf/}
  note          = {See https://pypdf.readthedocs.io/en/latest/meta/CONTRIBUTORS.html for all contributors}
 }

pypdf/_reader.py

@@ -213,7 +213,7 @@ def producer(self) -> Optional[str]:
         Read-only property accessing the document's producer.
 
         If the document was converted to PDF from another format, this is the
-        name of the application (for example, OSX Quartz) that converted it to
+        name of the application (for example, macOS Quartz) that converted it to
         PDF. Returns a ``TextStringObject`` or ``None`` if the producer is not
         specified.
         """
@@ -487,8 +487,8 @@ def named_destinations(self) -> Dict[str, Any]:
         """
         return self._get_named_destinations()
 
-    # A select group of relevant field attributes. For the complete list,
-    # see section 8.6.2 of the PDF 1.7 reference.
+    # 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,
@@ -1896,7 +1896,7 @@ def decrypt(self, password: Union[str, bytes]) -> PasswordType:
             password: The password to match.
 
         Returns:
-            An indicator if the document was decrypted and weather it was the
+            An indicator if the document was decrypted and whether it was the
             owner password or the user password.
         """
         if not self._encryption:

pypdf/generic/_data_structures.py

@@ -390,11 +390,10 @@ def xmp_metadata(self) -> Optional[PdfObject]:
         Retrieve XMP (Extensible Metadata Platform) data relevant to the this
         object, if available.
 
-        Stability: Added in v1.12, will exist for all future v1.x releases.
-        See Table 315 – Additional entries in a metadata stream dictionary
+        See Table 347 — Additional entries in a metadata stream dictionary.
 
         Returns:
-          Returns a {@link #xmp.XmpInformation XmlInformation} instance
+          Returns a :class:`~pypdf.xmp.XmpInformation` instance
           that can be used to access XMP metadata from the document.  Can also
           return None if no metadata was found on the document root.
         """
@@ -969,20 +968,23 @@ def set_data(self, data: bytes) -> None:  # deprecated
 
 class ContentStream(DecodedStreamObject):
     """
-    In order to be fast, this datastructure can contain either:
+    In order to be fast, this data structure can contain either:
+
     * raw data in ._data
-    * parsed stream operations in ._operations
+    * parsed stream operations in ._operations.
+
+    At any time, ContentStream object can either have both of those fields defined,
+    or one field defined and the other set to None.
+
+    These fields are "rebuilt" lazily, when accessed:
 
-    At any time, ContentStream object can either have one or both of those fields defined,
-    and zero or one of those fields set to None.
+    * when .get_data() is called, if ._data is None, it is rebuilt from ._operations.
+    * when .operations is called, if ._operations is None, it is rebuilt from ._data.
 
-    Those fields are "rebuilt" lazily, when accessed:
-    * when .get_data() is called, if ._data is None, it is rebuilt from ._operations
-    * when .operations is called, if ._operations is None, it is rebuilt from ._data
+    Conversely, these fields can be invalidated:
 
-    On the other side, those fields can be invalidated:
-    * when .set_data() is called, ._operations is set to None
-    * when .operations is set, ._data is set to None
+    * when .set_data() is called, ._operations is set to None.
+    * when .operations is set, ._data is set to None.
     """
 
     def __init__(