Improve docstrings and docs formatting

guides/api-style.rst

@@ -73,8 +73,6 @@ We have a reasonably distinctive style when it comes to handling arguments:
   ``lists(elements, *, min_size=0, max_size=None, unique_by=None, unique=False)``.
   We intend to `migrate to this style after dropping Python 2 support <https://github.com/HypothesisWorks/hypothesis/issues/2130>`__
   in early 2020, with a gentle deprecation pathway.
-  New functions or argumemnts can implement a forward-compatible signature with
-  ``hypothesis.internal.reflection.reserved_to_kwonly``.
 * When adding arguments to strategies, think carefully about whether the user
   is likely to want that value to vary often. If so, make it a strategy instead
   of a value. In particular if it's likely to be common that they would want to

hypothesis-python/RELEASE.rst

@@ -0,0 +1,4 @@
+RELEASE_TYPE: patch
+
+This patch improves the formatting of some documentation, and fixes
+a few internal comments.  There is no user-visible change.

hypothesis-python/src/hypothesis/_settings.py

@@ -612,7 +612,7 @@ def _validate_deadline(x):
     default=False,
     options=(True, False),
     description="""
-If set to True, Hypothesis will print code for failing examples that can be used with
+If set to ``True``, Hypothesis will print code for failing examples that can be used with
 :func:`@reproduce_failure <hypothesis.reproduce_failure>` to reproduce the failing example.
 """,
 )

hypothesis-python/src/hypothesis/internal/reflection.py

@@ -140,9 +140,8 @@ def required_args(target, args=(), kwargs=()):
 
 def convert_keyword_arguments(function, args, kwargs):
     """Returns a pair of a tuple and a dictionary which would be equivalent
-    passed as positional and keyword args to the function. Unless function has.
-
-    **kwargs the dictionary will always be empty.
+    passed as positional and keyword args to the function. Unless function has
+    kwonlyargs or **kwargs the dictionary will always be empty.
     """
     argspec = inspect.getfullargspec(function)
     new_args = []

hypothesis-python/src/hypothesis/strategies/_internal/core.py

@@ -412,8 +412,8 @@ def floats(
     required to represent the generated float. Valid values are 16, 32, or 64.
     Passing ``width=32`` will still use the builtin 64-bit ``float`` class,
     but always for values which can be exactly represented as a 32-bit float.
-    Half-precision floats (``width=16``) are only supported on Python 3.6, or
-    if :pypi:`Numpy` is installed.
+    Half-precision floats (``width=16``) are not supported on Python 3.5,
+    unless :pypi:`Numpy` is installed.
 
     The exclude_min and exclude_max argument can be used to generate numbers
     from open or half-open intervals, by excluding the respective endpoints.
@@ -639,8 +639,8 @@ def sampled_from(elements):
     may also generate any combination of their members.
 
     Examples from this strategy shrink by replacing them with values earlier in
-    the list. So e.g. sampled_from((10, 1)) will shrink by trying to replace
-    1 values with 10, and sampled_from((1, 10)) will shrink by trying to
+    the list. So e.g. ``sampled_from([10, 1])`` will shrink by trying to replace
+    1 values with 10, and ``sampled_from([1, 10])`` will shrink by trying to
     replace 10 values with 1.
     """
     values = check_sample(elements, "sampled_from")
@@ -684,6 +684,7 @@ def lists(
 
     For example, the following will produce two columns of integers with both
     columns being unique respectively.
+
     .. code-block:: pycon
 
         >>> twoints = st.tuples(st.integers(), st.integers())
@@ -1692,19 +1693,18 @@ def datetimes(
         common source of bugs.
 
     :py:func:`hypothesis.extra.pytz.timezones` requires the :pypi:`pytz`
-    package, but provides all timezones in the Olsen database.  If you want to
-    allow naive datetimes, combine strategies like ``none() | timezones()``.
-
+    package, but provides all timezones in the Olsen database.
     :py:func:`hypothesis.extra.dateutil.timezones` requires the
     :pypi:`python-dateutil` package, and similarly provides all timezones
-    there.
+    there.  If you want to allow naive datetimes, combine strategies
+    like ``none() | timezones()``.
 
     Alternatively, you can create a list of the timezones you wish to allow
-    (e.g. from the standard library, :pypi:`dateutil`, or :pypi:`pytz`) and use
-    :py:func:`sampled_from`.  Ensure that simple values such as None or UTC
-    are at the beginning of the list for proper minimisation.
+    (e.g. from the standard library, :pypi:`dateutil <python-dateutil>`,
+    or :pypi:`pytz`) and use :py:func:`sampled_from`.
 
-    Examples from this strategy shrink towards midnight on January 1st 2000.
+    Examples from this strategy shrink towards midnight on January 1st 2000,
+    local time.
     """
     # Why must bounds be naive?  In principle, we could also write a strategy
     # that took aware bounds, but the API and validation is much harder.

hypothesis-python/src/hypothesis/utils/conventions.py

@@ -13,27 +13,19 @@
 #
 # END HEADER
 
-# Notes: we use instances of these objects as singletons which serve as
-# identifiers in various patches of code.  The more specific types
-# (DefaultValueType and InferType) exist so that typecheckers such as Mypy
-# can distinguish them from the others.  DefaultValueType is only used in
-# the Django extra.
-
 
 class UniqueIdentifier:
+    """A factory for sentinel objects with nice reprs."""
+
     def __init__(self, identifier):
         self.identifier = identifier
 
     def __repr__(self):
         return self.identifier
 
 
-class DefaultValueType(UniqueIdentifier):
-    pass
-
-
 class InferType(UniqueIdentifier):
-    pass
+    """We have a subclass for `infer` so we can type-hint public APIs."""
 
 
 infer = InferType("infer")