Improve docstrings for mktemp

src/_pytest/tmpdir.py

@@ -54,7 +54,20 @@ class TempPathFactory:
         return basename
 
     def mktemp(self, basename: str, numbered: bool = True) -> Path:
-        """makes a temporary directory managed by the factory"""
+        """Creates a new temporary directory managed by the factory.
+
+        :param basename:
+            Directory base name, must be a relative path.
+
+        :param numbered:
+            If True, ensure the directory is unique by adding a number
+            prefix greater than any existing one: ``basename="foo"`` and ``numbered=True``
+            means that this function will create directories named ``"foo-0"``,
+            ``"foo-1"``, ``"foo-2"`` and so on.
+
+        :return:
+            The path to the new directory.
+        """
         basename = self._ensure_relative_to_basetemp(basename)
         if not numbered:
             p = self.getbasetemp().joinpath(basename)
@@ -99,10 +112,9 @@ class TempdirFactory:
 
     _tmppath_factory = attr.ib(type=TempPathFactory)
 
-    def mktemp(self, basename: str, numbered: bool = True):
-        """Create a subdirectory of the base temporary directory and return it.
-        If ``numbered``, ensure the directory is unique by adding a number
-        prefix greater than any existing one.
+    def mktemp(self, basename: str, numbered: bool = True) -> py.path.local:
+        """
+        Same as :meth:`TempPathFactory.mkdir`, but returns a ``py.path.local`` object.
         """
         return py.path.local(self._tmppath_factory.mktemp(basename, numbered).resolve())