MAINT: Add deprecate_with_replacement to PdfWriter.find_bookmark (#2674)

Plus tiny changes to docstrings.

---------

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

pypdf/_doc_common.py

@@ -762,8 +762,8 @@ def open_destination(
     ) -> Union[None, Destination, TextStringObject, ByteStringObject]:
         """
         Property to access the opening destination (``/OpenAction`` entry in
-        the PDF catalog). It returns ``None`` if the entry does not exist is not
-        set.
+        the PDF catalog). It returns ``None`` if the entry does not exist
+        or is not set.
 
         Raises:
             Exception: If a destination is invalid.
@@ -795,7 +795,7 @@ def outline(self) -> OutlineType:
         """
         Read-only property for the outline present in the document
         (i.e., a collection of 'outline items' which are also known as
-        'bookmarks')
+        'bookmarks').
         """
         return self._get_outline()
 
@@ -1002,7 +1002,7 @@ def pages(self) -> List[PageObject]:
 
         For PdfWriter Only:
         Provides the capability to remove a page/range of page from the list
-        (using the del operator)
+        (using the del operator).
         Note: only the page entry is removed. As the objects beneath can be used
         elsewhere.
         A solution to completely remove them - if they are not used anywhere -
@@ -1138,16 +1138,14 @@ def remove_page(
         Remove page from pages list.
 
         Args:
-            page: int / PageObject / IndirectObject
-                PageObject : page to be removed. If the page appears many times
-                only the first one will be removed
-
-                IndirectObject: Reference to page to be removed
-
-                int: Page number to be removed
-
-            clean: replace PageObject with NullObject to prevent destination,
-                annotation to reference a detached page
+            page:
+                * :class:`int`: Page number to be removed.
+                * :class:`~pypdf._page.PageObject`: page to be removed. If the page appears many times
+                  only the first one will be removed.
+                * :class:`~pypdf.generic.IndirectObject`: Reference to page to be removed.
+
+            clean: replace PageObject with NullObject to prevent annotations
+                or destinations to reference a detached page.
         """
         if self.flattened_pages is None:
             self._flatten()

pypdf/_writer.py

@@ -64,6 +64,7 @@
     StreamType,
     _get_max_pdf_version_header,
     b_,
+    deprecate_with_replacement,
     logger_warning,
 )
 from .constants import AnnotationDictionaryAttributes as AA
@@ -883,7 +884,7 @@ def _update_field_annotation(
         ap_stream = f"q\n/Tx BMC \nq\n1 1 {rct.width - 1} {rct.height - 1} re\nW\nBT\n{da}\n".encode()
         for line_number, line in enumerate(txt.replace("\n", "\r").split("\r")):
             if line in sel:
-                # may be improved but can not find how get fill working => replaced with lined box
+                # may be improved but cannot find how to get fill working => replaced with lined box
                 ap_stream += (
                     f"1 {y_offset - (line_number * font_height * 1.4) - 1} {rct.width - 2} {font_height + 2} re\n"
                     f"0.5 0.5 0.5 rg s\n{da}\n"
@@ -2199,7 +2200,7 @@ def add_annotation(
         """
         Add a single annotation to the page.
         The added annotation must be a new annotation.
-        It can not be recycled.
+        It cannot be recycled.
 
         Args:
             page_number: PageObject or page index.
@@ -2847,6 +2848,7 @@ def find_bookmark(
         .. deprecated:: 2.9.0
             Use :meth:`find_outline_item` instead.
         """
+        deprecate_with_replacement("find_bookmark", "find_outline_item", "5.0.0")
         return self.find_outline_item(outline_item, root)
 
     def reset_translation(