diff --git a/man/man3/pmjsoninit.3 b/man/man3/pmjsoninit.3
index a85dbf1..fc5fd0d 100644
--- a/man/man3/pmjsoninit.3
+++ b/man/man3/pmjsoninit.3
@@ -25,11 +25,11 @@
 .hy 0
 .in +8n
 .ti -8n
-int pmjsonInitIndom(FILE *\fIfd\fP, json_metric_desc *\fIjson_metrics\fP,
+int pmjsonInitIndom(int \fIfd\fP, json_metric_desc *\fIjson_metrics\fP,
 int \fInum_metrics\fP, pmInDom \fIindom\fP);
 .br
 .ti -8n
-int pmjsonInit(FILE *\fIfp\fP, json_metric_desc *\fIjson_metrics\fP,
+int pmjsonInit(int \fIfd\fP, json_metric_desc *\fIjson_metrics\fP,
 int \fInum_metrics\fP);
 .sp
 .in
@@ -39,31 +39,34 @@ cc ... \-lpcp_json \-lpcp
 .ft 1
 .SH DESCRIPTION
 .P
-\f3pmjsonInitIndom\f1 creates and initializes the JSON parsing
-functionality.  Returning the results of the requested metrics (as
-defined in the json_pointer field) in the values field.
+\f3pmjsonInitIndom\f1 creates and initializes JSON metric extraction
+functionality for PCP metrics with instance domains.
+Metrics and instances are defined by the \f2json_metrics\f1 parameter.
+The result of parsing is the extraction of values for the requested
+metrics (as defined in the json_pointer field) in the values field.
 .P
-\f3pmjsonInit\f1 specifies a call to the JSON parsing and
-metric extraction functionality where there are no instance
-domains.
-Or the PMDA wishes to perform instance domain operations itself.
+\f3pmjsonInit\f1 specifies a call to the JSON parsing and metric
+value extraction functionality where there are no instance domains,
+or the PMDA wishes to perform instance domain operations itself.
 .P
-\f2fd\f1 The file descriptor to the json document.
+\f2fd\f1 is an open file descriptor from which the JSON document will
+be read.
 .P
-\f2json_metrics\f1 Is the array of json_metric_desc struct which
+\f2json_metrics\f1 is the array of json_metric_desc struct which
 contains the json pointer to the metric data, possible flags to check
 the data against, number of values (in the case of an array),
 \f2pmAtomValue\f1 where the data is stored, as well as the instance
 domain in the even the PMDA in question has multiple domains.
 \f3pmjsonInitIndom\f1 will endeavour to make use of the
-\f3pmdaCacheAdd(3)\f1 function where possible.
+.BR pmdaCacheAdd (3)
+function where possible.
 In the event that no \f2indom\f1 is needed, PM_INDOM_NULL should be
-passed, or \f3pmjsonInit\f1 should be used instead.
+passed, or \f3pmjsonInit\f1 used instead.
 .P
-\f2num_metrics\f1 Is the number of elements in in the array of
-json_metrics.
+\f2num_metrics\f1 is the number of elements in in the array of
+.IR json_metrics .
 .P
-\f2indom\f1 Is the instance domain to be passed to \f3pmdaCacheAdd\f1.
+\f2indom\f1 is the instance domain to be passed to \f3pmdaCacheAdd\f1.
 .P
 .nf
 	typedef struct json_metrics_desc {
@@ -76,9 +79,7 @@ json_metrics.
 .fi
 .P
 The JSON Pointer syntax current follows \f2RFC6901\f1 in specifying a
-metric's location within the json document.
-.SH RETURNS
-The function returns zero on success and the error code on failure.
+metrics location within the JSON document.
 .SH EXAMPLE
 .ft CW
 .nf
@@ -112,7 +113,13 @@ static json_metric_desc json_metrics[] = {
 };
 .fi
 .ft R
+.SH RETURN CODE
+The function returns zero on success, otherwise an error code suitable
+for passing to
+.BR pmErrStr_r (3)
+is returned.
 .SH SEE ALSO
+.BR pmErrStr_r (3),
 .BR pmdaCacheAdd (3),
 .nh
 .BR http://json.org/ ,
@@ -123,6 +130,3 @@ static json_metric_desc json_metrics[] = {
 .nh
 .BR https://tools.ietf.org/html/rfc6901 ,
 .ny
-
-
-