Fix docstring & type annotation for to_markdown buf parameter

Author: jakevdp

pandas/core/frame.py

@@ -2015,7 +2015,10 @@ def to_feather(self, path) -> None:
     @Substitution(klass="DataFrame")
     @Appender(_shared_docs["to_markdown"])
     def to_markdown(
-        self, buf: Optional[IO[str]] = None, mode: Optional[str] = None, **kwargs
+        self,
+        buf: Optional[FilePathOrBuffer] = None,
+        mode: Optional[str] = None,
+        **kwargs,
     ) -> Optional[str]:
         kwargs.setdefault("headers", "keys")
         kwargs.setdefault("tablefmt", "pipe")

pandas/core/generic.py

@@ -1922,10 +1922,8 @@ def _repr_data_resource_(self):
 
     Parameters
     ----------
-    buf : writable buffer, defaults to sys.stdout
-        Where to send the output. By default, the output is printed to
-        sys.stdout. Pass a writable buffer if you need to further process
-        the output.
+    buf : str, Path or StringIO-like, optional, default None
+        Buffer to write to. If None, the output is returned as a string.
     mode : str, optional
         Mode in which file is opened.
     **kwargs

pandas/core/series.py

@@ -23,7 +23,7 @@
 from pandas._config import get_option
 
 from pandas._libs import index as libindex, lib, properties, reshape, tslibs
-from pandas._typing import Label
+from pandas._typing import FilePathOrBuffer, Label
 from pandas.compat.numpy import function as nv
 from pandas.util._decorators import Appender, Substitution
 from pandas.util._validators import validate_bool_kwarg, validate_percentile
@@ -1454,7 +1454,10 @@ def to_string(
     @Substitution(klass="Series")
     @Appender(generic._shared_docs["to_markdown"])
     def to_markdown(
-        self, buf: Optional[IO[str]] = None, mode: Optional[str] = None, **kwargs
+        self,
+        buf: Optional[FilePathOrBuffer] = None,
+        mode: Optional[str] = None,
+        **kwargs,
     ) -> Optional[str]:
         return self.to_frame().to_markdown(buf, mode, **kwargs)