Add some docstrings

1 files changed, 90 insertions, 0 deletions

diff --git a/prometheus.scm b/prometheus.scm
index 6c45ad3..024f578 100644
--- a/prometheus.scm
+++ b/prometheus.scm
@@ -46,6 +46,14 @@
   (namespace       metrics-registry-namespace))
 
 (define* (make-metrics-registry #:key namespace)
+  "Create a metrics registry. This record stores named metrics, and
+can have an optional @var{namespace}.
+
+The @var{namespace} is used when writing out the metrics, each metric
+name will be prefixed by the @var{namespace}, separated with an
+underscore. Convention for naming metrics is that the @var{namespace}
+should be a single word that identifies the application or area the
+metrics relate to."
   (make-metrics-registry-record (make-hash-table)
                                 namespace))
 
@@ -76,6 +84,7 @@
     metric))
 
 (define (metrics-registry-fetch-metric registry name)
+  "Fetch a metric by @var{name} from the @var{registry}"
   (hash-ref (metrics-registry-metrics-hash registry)
             name))
 
@@ -84,6 +93,18 @@
                               docstring
                               (labels '())
                               (label-preset-values '()))
+  "Make a counter metric, to track a value that only increases aside
+from when it resets to 0 normally when the collector restarts. The
+metric is associated with the specified @var{registry} under the given
+@var{name}.
+
+A metric record is returned, the value of the metric can be changed
+with the @code{metric-increment} procedure.
+
+The following keyword arguments can be used with all metrics:
+@var{#:docstring} a short description of the metric, @var{#:labels} a
+list of label names to be permitted for this metric and
+@var{#:label-preset-values} default values for labels."
   (metrics-registry-add-metric
    registry
    name
@@ -101,6 +122,18 @@
                             docstring
                             (labels '())
                             (label-preset-values '()))
+  "Make a gauge metric, to track a value that can go up or down. The
+metric is associated with the specified @var{registry} under the given
+@var{name}.
+
+A metric record is returned, the value of the metric can be changed
+with the @code{metric-increment}, @code{metric-decrement} or
+@code{metric-set} procedures.
+
+The following keyword arguments can be used with all metrics:
+@var{#:docstring} a short description of the metric, @var{#:labels} a
+list of label names to be permitted for this metric and
+@var{#:label-preset-values} default values for labels."
   (metrics-registry-add-metric
    registry
    name
@@ -128,6 +161,21 @@
                                 docstring
                                 (labels '())
                                 (label-preset-values '()))
+  "Make a histogram metric, to track observations of values in a set
+of buckets. Quantiles can be calculated from the histogram, which
+makes this metric type good for observing things like durations.
+
+Internally, this metric represents multiple metrics. One for each
+bucket, plus one to record the total of all observed values and
+another to count the number of observations.
+
+A metric record is returned, this can be used with the
+@code{metric-observe} procedure.
+
+The following keyword arguments can be used with all metrics:
+@var{#:docstring} a short description of the metric, @var{#:labels} a
+list of label names to be permitted for this metric and
+@var{#:label-preset-values} default values for labels."
   ;; TODO validate buckets
 
   (metrics-registry-add-metric
@@ -178,6 +226,13 @@
                            #:key
                            (by 1)
                            (label-values '()))
+  "Increment the value of the given @var{metric} by 1 (or the @var{#:by} value).
+
+This procedure can be used with counter or gauge metrics.
+
+To specify values for the labels, pass an alist as
+@var{#:label-values} where the keys are the label names, and the
+values are the values."
   (unless (memq (metric-type metric)
                 '(counter gauge))
     (error "can only increment counter and gauge metrics"))
@@ -200,6 +255,13 @@
                            #:key
                            (by 1)
                            (label-values '()))
+  "Decrement the value of the given @var{metric} by 1 (or the @var{#:by} value).
+
+This procedure can be used with gauge metrics.
+
+To specify values for the labels, pass an alist as
+@var{#:label-values} where the keys are the label names, and the
+values are the values."
   (unless (memq (metric-type metric)
                 '(gauge))
     (error "can only increment gauge metrics"))
@@ -217,6 +279,13 @@
 
 (define* (metric-set metric value
                      #:key (label-values '()))
+  "Set the value of the given @var{metric} to @var{value}.
+
+This procedure can be used with gauge metrics.
+
+To specify values for the labels, pass an alist as
+@var{#:label-values} where the keys are the label names, and the
+values are the values."
   (unless (memq (metric-type metric)
                 '(gauge))
     (error "can only set gauge metrics"))
@@ -228,6 +297,14 @@
 
 (define* (metric-observe metric value
                          #:key (label-values '()))
+  "With the given @var{metric}, observe the given @var{value}.
+
+This procedure can be used with histogram metrics.
+
+To specify values for the labels, pass an alist as
+@var{#:label-values} where the keys are the label names, and the
+values are the values."
+
   (unless (histogram-metric-type? (metric-type metric))
     (error "can only observe histogram metrics"))
 
@@ -264,6 +341,13 @@
          buckets)))))
 
 (define (call-with-duration-metric registry metric-name thunk)
+  "Call @var{thunk} while recording the duration in seconds between
+calling @var{thunk} and the procedure ending using a metric by the
+name of @var{metric-name}.
+
+The metric with the name @var{metric-name} is fetched from the
+@var{registry}, or created if it doesn't already exist.
+"
   (let* ((metric
           (or (metrics-registry-fetch-metric registry metric-name)
               (make-histogram-metric
@@ -275,6 +359,12 @@
       result)))
 
 (define (write-metrics registry port)
+  "Write all metrics from the given @var{registry} to @var{port} in
+the standard text based exposition format.
+
+Usually, this would be in response to a HTTP request from Prometheus
+so that it can receive and store the metric values."
+
   (hash-for-each
    (lambda (name metric)
      (hash-for-each