DOC: update docstrings following refactor of buffer handling

pandas/core/generic.py

@@ -68,6 +68,7 @@
 from pandas.core.internals import BlockManager
 from pandas.core.ops import _align_method_FRAME
 
+from pandas.io.formats import format as fmt
 from pandas.io.formats.format import DataFrameFormatter, format_percentiles
 from pandas.io.formats.printing import pprint_thing
 from pandas.tseries.frequencies import to_offset
@@ -2881,6 +2882,7 @@ class      (index) object 'bird' 'bird' 'mammal' 'mammal'
         else:
             return xarray.Dataset.from_dataframe(self)
 
+    @Substitution(returns=fmt.return_docstring)
     def to_latex(
         self,
         buf=None,
@@ -2914,7 +2916,7 @@ def to_latex(
 
         Parameters
         ----------
-        buf : file descriptor or None
+        buf : str, Path or StringIO-like, optional, default None
             Buffer to write to. If None, the output is returned as a string.
         columns : list of label, optional
             The subset of columns to write. Writes all columns by default.
@@ -2979,13 +2981,7 @@ def to_latex(
             from the pandas config module.
 
             .. versionadded:: 0.20.0
-
-        Returns
-        -------
-        str or None
-            If buf is None, returns the resulting LateX format as a
-            string. Otherwise returns None.
-
+        %(returns)s
         See Also
         --------
         DataFrame.to_string : Render a DataFrame to a console-friendly

pandas/io/formats/format.py

@@ -85,8 +85,8 @@
 common_docstring = """
         Parameters
         ----------
-        buf : StringIO-like, optional
-            Buffer to write to.
+        buf : str, Path or StringIO-like, optional, default None
+            Buffer to write to. If None, the output is returned as a string.
         columns : sequence, optional, default None
             The subset of columns to write. Writes all columns by default.
         col_space : %(col_space_type)s, optional
@@ -156,8 +156,9 @@
 return_docstring = """
         Returns
         -------
-        str (or unicode, depending on data and options)
-            String representation of the dataframe.
+        str or None
+            If buf is None, returns the result as a string. Otherwise returns
+            None.
     """
 
 
@@ -471,6 +472,10 @@ def _get_formatter(self, i: Union[str, int]) -> Optional[Callable]:
     def get_buffer(
         self, buf: Optional[FilePathOrBuffer[str]], encoding: Optional[str] = None
     ):
+        """
+        Context manager to open, yield and close buffer for filenames or Path-like
+        objects, otherwise yield buf unchanged.
+        """
         if buf is not None:
             buf = _stringify_path(buf)
         else:
@@ -488,13 +493,19 @@ def get_buffer(
             raise TypeError("buf is not a file name and it has no write method")
 
     def write_result(self, buf: IO[str]) -> None:
+        """
+        Write the result of serialization to buf.
+        """
         raise AbstractMethodError(self)
 
     def get_result(
         self,
         buf: Optional[FilePathOrBuffer[str]] = None,
         encoding: Optional[str] = None,
     ) -> Optional[str]:
+        """
+        Perform serialization. Write to buf or return as string if buf is None.
+        """
         with self.get_buffer(buf, encoding=encoding) as f:
             self.write_result(buf=f)
             if buf is None: