Improve the docs a bit (just editorial)

README.rst

@@ -37,8 +37,8 @@ DESCRIPTION
 ===========
 
 This Varnish Module (VMOD) makes details about the health of a backend
-available in VCL. This is the information that is shown as the reult the
-``backend.list`` command in the Varnish CLI, which is commonly invoked
+available in VCL -- the information shown in the output of the
+``backend.list`` command of the Varnish CLI, which is commonly invoked
 via ``varnishadm``.
 
 If a health probe has been defined for a backend, then its health or
@@ -46,17 +46,17 @@ sickness may be determined by the results of the probe. But if the
 ``backend.set_health`` command has been invoked to set the backend
 manually to healthy or sick, then that health state will apply in the
 decisions that Varnish makes to choose backends. The ``std.healthy()``
-method from the ``std`` VMOD returns the result of that decision, but
-does not distinguish whether it resulted from a probe or from the use
-of ``backend.set_health``.
-
-The functions in this VMOD make that distinction possible -- it can be
-determined, for example, that a backend is healthy according to its
-probe, but has been set to sick via the CLI. The states of
-administrative health are the same as those seen in the output for the
-``backend.list`` command: ``probe``, ``healthy`` or ``sick`` if the
-backend health is determined by the probe, manually set to healthy, or
-manually set to unhealthy, respectively.
+function from the ``std`` VMOD returns the result of that decision,
+but does not distinguish whether it resulted from a probe or from the
+use of ``backend.set_health``.
+
+The functions in this VMOD make that distinction possible in VCL -- it
+can be determined, for example, that a backend is healthy according to
+its probe, but has been set to sick via the CLI. The states of
+administrative health are the same as those seen in the output of
+``backend.list`` command: ``"probe"``, ``"healthy"`` or ``"sick"`` if
+the backend health is determined by the probe, manually set to
+healthy, or manually set to unhealthy, respectively.
 
 Examples::
 
@@ -131,17 +131,18 @@ probe_healthy
 
 	BOOL probe_healthy(BACKEND)
 
-Return whether a backend is healthy according to the results of its probe,
-independent of any manual state set by ``backend.set_health``.
+Return true if the backend is healthy according to the results of its
+probe, independent of any state set manually by
+``backend.set_health``.
 
-This function MUST be invoked only if a probe is assigned to the backend,
-which is not necessarily true of every backend. If it is called for a
-backend without a probe, then VCL failure is invoked: response status
-503 is returned, and an error message with the tag ``VCL_Error`` is
-emitted to the log.
+This function MAY NOT be invoked for a backend unless a probe is
+assigned to it, which is not necessarily the case for every
+backend. If it is called for a backend without a probe, then VCL
+failure is invoked: response status 503 is returned, and an error
+message with the tag ``VCL_Error`` is emitted to the Varnish log.
 
-To avoid that, you can call the ``has_probe()`` function before calling
-this function.
+To avoid that, call ``has_probe()`` first, and call this function only
+if ``has_probe()`` returns true.
 
 Example::
 

src/vmod_health.vcc

@@ -20,8 +20,8 @@ DESCRIPTION
 ===========
 
 This Varnish Module (VMOD) makes details about the health of a backend
-available in VCL. This is the information that is shown as the reult the
-``backend.list`` command in the Varnish CLI, which is commonly invoked
+available in VCL -- the information shown in the output of the
+``backend.list`` command of the Varnish CLI, which is commonly invoked
 via ``varnishadm``.
 
 If a health probe has been defined for a backend, then its health or
@@ -29,17 +29,17 @@ sickness may be determined by the results of the probe. But if the
 ``backend.set_health`` command has been invoked to set the backend
 manually to healthy or sick, then that health state will apply in the
 decisions that Varnish makes to choose backends. The ``std.healthy()``
-method from the ``std`` VMOD returns the result of that decision, but
-does not distinguish whether it resulted from a probe or from the use
-of ``backend.set_health``.
-
-The functions in this VMOD make that distinction possible -- it can be
-determined, for example, that a backend is healthy according to its
-probe, but has been set to sick via the CLI. The states of
-administrative health are the same as those seen in the output for the
-``backend.list`` command: ``probe``, ``healthy`` or ``sick`` if the
-backend health is determined by the probe, manually set to healthy, or
-manually set to unhealthy, respectively.
+function from the ``std`` VMOD returns the result of that decision,
+but does not distinguish whether it resulted from a probe or from the
+use of ``backend.set_health``.
+
+The functions in this VMOD make that distinction possible in VCL -- it
+can be determined, for example, that a backend is healthy according to
+its probe, but has been set to sick via the CLI. The states of
+administrative health are the same as those seen in the output of
+``backend.list`` command: ``"probe"``, ``"healthy"`` or ``"sick"`` if
+the backend health is determined by the probe, manually set to
+healthy, or manually set to unhealthy, respectively.
 
 Examples::
 
@@ -91,17 +91,18 @@ Example::
 
 $Function BOOL probe_healthy(BACKEND)
 
-Return whether a backend is healthy according to the results of its probe,
-independent of any manual state set by ``backend.set_health``.
+Return true if the backend is healthy according to the results of its
+probe, independent of any state set manually by
+``backend.set_health``.
 
-This function MUST be invoked only if a probe is assigned to the backend,
-which is not necessarily true of every backend. If it is called for a
-backend without a probe, then VCL failure is invoked: response status
-503 is returned, and an error message with the tag ``VCL_Error`` is
-emitted to the log.
+This function MAY NOT be invoked for a backend unless a probe is
+assigned to it, which is not necessarily the case for every
+backend. If it is called for a backend without a probe, then VCL
+failure is invoked: response status 503 is returned, and an error
+message with the tag ``VCL_Error`` is emitted to the Varnish log.
 
-To avoid that, you can call the ``has_probe()`` function before calling
-this function.
+To avoid that, call ``has_probe()`` first, and call this function only
+if ``has_probe()`` returns true.
 
 Example::