DOC: Improve docstrings (py-pdf#2690)

Author: j-t-1

CONTRIBUTING.md

@@ -15,9 +15,9 @@ Please use the templates provided.
 We appreciate if people make PRs, but please be aware that pypdf is used by many
 people. That means:
 
-* We rarely make breaking changes and have a [deprecation process](https://pypdf.readthedocs.io/en/latest/dev/deprecations.html)
+* We rarely make breaking changes and have a [deprecation process](https://pypdf.readthedocs.io/en/latest/dev/deprecations.html).
 * New features, especially adding to the public interface, typically need to be
   discussed first.
 
-Before you make bigger changes, rather open an issue to make the suggestion.
+Before you make bigger changes, open an issue to make the suggestion.
 Note which interface changes you want to make.

CONTRIBUTORS.md

@@ -1,13 +1,13 @@
 # Contributors
 
-pypdf had a lot of contributors since it started with pyPdf in 2005. We are
+pypdf had a lot of contributors since it started as pyPdf in 2005. We are
 a free software project without any company affiliation. We cannot pay
 contributors, but we do value their contributions. A lot of time, effort, and
-expertise went into this project. With this list, we recognize those awesome
+expertise went into this project. With this list, we recognize these awesome
 people 🤗
 
 The list is definitely not complete. You can find more contributors via the git
-history and [GitHubs 'Contributors' feature](https://github.com/py-pdf/pypdf/graphs/contributors).
+history and [GitHub's 'Contributors' feature](https://github.com/py-pdf/pypdf/graphs/contributors).
 
 ## Contributors to the pypdf (formerly pyPdf / PyPDF2) project
 

docs/user/adding-pdf-annotations.md

@@ -221,8 +221,6 @@ Manage the Popup windows for markups. looks like this:
 
 you can use the {py:class}`Popup <pypdf.annotations.Popup>`:
 
-you have to use the returned result from add_annotation() to fill-up the
-
 ```python
 from pypdf.annotations import Popup, Text
 
@@ -249,6 +247,9 @@ popup_annotation = Popup(
 writer.write("annotated-pdf-popup.pdf")
 ```
 
+You have to use the returned result from add_annotation() as it is
+the parent annotation with which this popup annotation shall be associated.
+
 ## Link
 
 If you want to add a link, you can use
@@ -303,7 +304,7 @@ with open("annotated-pdf.pdf", "wb") as fp:
 
 Text markup annotations refer to a specific piece of text within the document.
 
-Those are a bit more complicated as you need to know exactly where the text
+These are a bit more complicated as you need to know exactly where the text
 is, the so-called "Quad points".
 
 ### Highlighting

pypdf/generic/__init__.py

@@ -110,7 +110,7 @@ class AnnotationBuilder:
     Instead, use the annotation classes in pypdf.annotations.
 
     See `adding PDF annotations <../user/adding-pdf-annotations.html>`_ for
-    it's usage combined with PdfWriter.
+    its usage combined with PdfWriter.
     """
 
     from ..generic._rectangle import RectangleObject
@@ -341,7 +341,7 @@ def ellipse(
         interiour_color: Optional[str] = None,
     ) -> DictionaryObject:
         """
-        Draw a rectangle on the PDF.
+        Draw an ellipse on the PDF.
 
         This method uses the /Circle annotation type of the PDF format.