docs: improve API documentation (#489)

This is a bunch of miscellaneous doc rendering issues I came across.

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://togithub.com/googleapis/python-bigquery-dataframes/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

Author: shobsi

third_party/bigframes_vendored/pandas/core/arrays/datetimelike.py

@@ -33,7 +33,7 @@ def strftime(self, date_format: str):
                 Date format string (e.g. "%Y-%m-%d").
 
         Returns:
-            bigframes.series.Series of formatted strings.
+            bigframes.series.Series: Series of formatted strings.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 

third_party/bigframes_vendored/pandas/core/frame.py

@@ -1141,7 +1141,7 @@ def align(
 
         Args:
             other (DataFrame or Series):
-            join ({{'outer', 'inner', 'left', 'right'}}, default 'outer'):
+            join ({'outer', 'inner', 'left', 'right'}, default 'outer'):
                 Type of alignment to be performed.
                 left: use only keys from left frame, preserve key order.
                 right: use only keys from right frame, preserve key order.
@@ -1627,9 +1627,6 @@ def keys(self):
 
         This is index for Series, columns for DataFrame.
 
-        Returns:
-            Index: Info axis.
-
         **Examples:**
 
             >>> import bigframes.pandas as bpd
@@ -1641,6 +1638,9 @@ def keys(self):
             ...     })
             >>> df.keys()
             Index(['A', 'B'], dtype='object')
+
+        Returns:
+            Index: Info axis.
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 
@@ -1673,6 +1673,17 @@ def itertuples(self, index: bool = True, name: str | None = "Pandas"):
         """
         Iterate over DataFrame rows as namedtuples.
 
+        **Examples:**
+
+            >>> import bigframes.pandas as bpd
+            >>> bpd.options.display.progress_bar = None
+            >>> df = bpd.DataFrame({
+            ...     'A': [1, 2, 3],
+            ...     'B': [4, 5, 6],
+            ...     })
+            >>> next(df.itertuples(name="Pair"))
+            Pair(Index=0, A=1, B=4)
+
         Args:
             index (bool, default True):
                 If True, return the index as the first element of the tuple.
@@ -1685,18 +1696,6 @@ def itertuples(self, index: bool = True, name: str | None = "Pandas"):
                 An object to iterate over namedtuples for each row in the
                 DataFrame with the first field possibly being the index and
                 following fields being the column values.
-
-
-        **Examples:**
-
-            >>> import bigframes.pandas as bpd
-            >>> bpd.options.display.progress_bar = None
-            >>> df = bpd.DataFrame({
-            ...     'A': [1, 2, 3],
-            ...     'B': [4, 5, 6],
-            ...     })
-            >>> next(df.itertuples(name="Pair"))
-            Pair(Index=0, A=1, B=4)
         """
         raise NotImplementedError(constants.ABSTRACT_METHOD_ERROR_MESSAGE)
 
@@ -3155,7 +3154,7 @@ def join(self, other, *, on: Optional[str] = None, how: str) -> DataFrame:
             on:
                 Column in the caller to join on the index in other, otherwise
                 joins index-on-index. Like an Excel VLOOKUP operation.
-            how ({'left', 'right', 'outer', 'inner'}, default 'left'`):
+            how ({'left', 'right', 'outer', 'inner'}, default 'left'):
                 How to handle the operation of the two objects.
                 ``left``: use calling frame's index (or column if on is specified)
                 ``right``: use `other`'s index. ``outer``: form union of calling