Improving docstrings

fpdf/enums.py

@@ -775,7 +775,3 @@ class EncryptionMethod(Enum):
     NO_ENCRYPTION = 0
     RC4 = 1
     AES_128 = 2
-
-
-# This enum is only used internally:
-__pdoc__ = {"DocumentState": False}

fpdf/fpdf.py

@@ -942,7 +942,7 @@ def footer(self):
         """
         Footer to be implemented in your own inherited class.
 
-        This is automatically called by `FPDF.add_page()` and `FPDF.close()`
+        This is automatically called by `FPDF.add_page()` and `FPDF.output()`
         and should not be called directly by the user application.
         The default implementation performs nothing: you have to override this method
         in a subclass to implement your own rendering logic.
@@ -4570,6 +4570,7 @@ def use_font_style(self, font_style: FontStyle):
     def table(self):
         """
         Inserts a table, that can be built using the `fpdf.table.Table` object yield.
+        Detailed usage documentation: https://pyfpdf.github.io/fpdf2/Tables.html
         """
         table = Table(self)
         yield table

fpdf/image_parsing.py

@@ -25,7 +25,7 @@
 def load_image(filename):
     """
     This method is used to load external resources, such as images.
-    It is automatically called when resource added to document by `FPDF.image()`.
+    It is automatically called when resource added to document by `fpdf.FPDF.image()`.
     It always return a BytesIO buffer.
     """
     # if a bytesio instance is passed in, use it as is.

fpdf/table.py

@@ -10,7 +10,10 @@
 
 
 class Table:
-    "Object that `FPDF.table()` yields, used to build a table in the document"
+    """
+    Object that `fpdf.FPDF.table()` yields, used to build a table in the document.
+    Detailed usage documentation: https://pyfpdf.github.io/fpdf2/Tables.html
+    """
 
     def __init__(self, fpdf):
         self._fpdf = fpdf
@@ -47,7 +50,7 @@ def row(self):
         yield row
 
     def render(self):
-        "This is an internal method called by `FPDF.table()` once the table is finished"
+        "This is an internal method called by `fpdf.FPDF.table()` once the table is finished"
         if self.width > self._fpdf.epw:
             raise ValueError(
                 f"Invalid value provided .width={self.width}: effective page width is {self._fpdf.epw}"
@@ -87,7 +90,7 @@ def get_cell_border(self, i, j):
         """
         Defines which cell borders should be drawn.
         Returns a string containing some or all of the letters L/R/T/B,
-        to be passed to `FPDF.multi_cell()`.
+        to be passed to `fpdf.FPDF.multi_cell()`.
         Can be overriden to customize this logic
         """
         if self.borders_layout == TableBordersLayout.ALL.value:
@@ -190,7 +193,7 @@ def _render_table_cell(
         lines = self._fpdf.multi_cell(
             w=col_width,
             h=row_height,
-            txt=cell.text or "",
+            txt=cell.text,
             max_line_height=cell_line_height,
             border=self.get_cell_border(i, j),
             align=text_align,
@@ -236,15 +239,17 @@ def _get_lines_heights_per_cell(self, i) -> List[List[int]]:
 
 
 class Row:
-    "Object that FPDF.row() yields, used to build a row in a table"
+    "Object that `Table.row()` yields, used to build a row in a table"
 
     def __init__(self):
         self.cells = []
 
-    def cell(self, text=None, img=None, img_fill_width=False):
+    def cell(self, text="", img=None, img_fill_width=False):
         """
+        Adds a cell to the row.
+
         Args:
-            text (str): optional. String content, can contain several lines.
+            text (str): string content, can contain several lines.
                 In that case, the row height will grow proportionally.
             img: optional. Either a string representing a file path to an image,
                 an URL to an image, an io.BytesIO, or a instance of `PIL.Image.Image`.