adding some more docs

.gitignore

@@ -1,4 +1,7 @@
 *.beam
 *.ez
+.history
 /build
 erl_crash.dump
+todo.md
+test/docs_test.gleam

README.md

@@ -19,16 +19,16 @@ gleam add promgleam
 [(Source)](https://prometheus.io/docs/concepts/metric_types/#counter)
 
 ```gleam
-import promgleam/metrics/counter.{new_counter, inc_counter}
+import promgleam/metrics/counter.{create_counter, increment_counter}
 
-new_counter(
+create_counter(
  registry: "default",
  name: "http_requests_total",
  help: "Total number of HTTP requests",
  labels: [ "method", "route", "status" ],
 )
 
-inc_counter(
+increment_counter(
  registry: "default",
  name: "http_requests_total",
  labels: [ "GET", "/", "200" ],
@@ -43,19 +43,19 @@ Gauges are typically used for measured values like temperatures or current memor
 [(Source)](https://prometheus.io/docs/concepts/metric_types/#gauge)
 
 ```gleam
-import promgleam/metrics/gauge.{new_gauge, set_gauge}
+import promgleam/metrics/gauge.{create_gauge, set_gauge}
 
-new_gauge(
+create_gauge(
  registry: "default",
  name: "cache_size",
  help: "Number of items in the cache",
  labels: [ "cache_name" ],
 )
 
-inc_counter(
+set_gauge(
  registry: "default",
  name: "cache_size",
- labels: [ "users" ],
+ labels: [ "image_cache" ],
  value: 123,
 )
 ```
@@ -66,14 +66,14 @@ inc_counter(
 [(Source)](https://prometheus.io/docs/concepts/metric_types/#histogram)
 
 ```gleam
-import promgleam/metrics/histogram.{new_histogram, observe_histogram}
+import promgleam/metrics/histogram.{create_histogram, observe_histogram}
 
-new_histogram(
+create_histogram(
  registry: "default",
  name: "http_request_duration_seconds",
  help: "Duration of HTTP requests in seconds",
  labels: [ "method", "route", "status" ],
- buckets: [ 0.1, 0.25, 0.5, 1.0, 1.5 ]
+ buckets: [ 0.1, 0.25, 0.5, 1.0, 1.5 ],
 )
 
 observe_histogram(
@@ -91,17 +91,17 @@ This library provides utility functions to create `buckets` for a Histogram:
 ```gleam
 import promgleam/buckets.{exponential, linear}
 
-exponential(start: 1.0, factor: 2, count: 5) // [1.0, 2.0, 4.0, 8.0, 10.0]
-linear(start: 1.0, step: 3.0, count: 4) // [1.0, 4.0, 7.0, 10.0]
+exponential(start: 1.0, factor: 2, count: 5) // Ok([1.0, 2.0, 4.0, 8.0, 10.0])
+linear(start: 1.0, step: 3.0, count: 4) // Ok([1.0, 4.0, 7.0, 10.0])
 ```
-### Printing the content of a metric registry
+### Printing the contents of a metric registry
 
 This can be done by using one of the `print_as` functions:
-- `print_as_text` - Returns a `String` using the [Prometheus text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-format-example)
-- `print_as_prometheus` - Returns a `BitArray` using the [Prometheus Protobuf format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#protobuf-format)
+- `print_as_text` - Serialises the registry using the [Prometheus text-based format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-format-example) into a `String`
+- `print_as_prometheus` - Serialises the registry using the [Prometheus Protobuf format](https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#protobuf-format) into a `BitArray`
 
 ```gleam
-import promgleam/print.{print_as_text, print_as_protobuf}
+import promgleam/registry.{print_as_text, print_as_protobuf}
 
 print_as_text(registry_name: "default")
 print_as_protobuf(registry_name: "default")

gleam.toml

@@ -4,6 +4,12 @@ description = "A Prometheus client library for Gleam"
 licences = ["Apache-2.0"]
 repository = { type = "github", user = "dios-david", repo = "promgleam" }
 target = "erlang"
+internal_modules = [
+ "internal",
+ "internal/*",
+ "promgleam/internal",
+ "promgleam/internal/*"
+]
 
 [dependencies]
 gleam_erlang = ">= 0.25.0 and < 1.0.0"

src/buckets.gleam

@@ -1,5 +1,7 @@
+//// Utility functions to generate buckets for Histogram metrics.
+
 import gleam/string.{from_utf_codepoints}
-import prometheus_error.{type PrometheusError, InvalidValue}
+import internal/prometheus_error.{type PrometheusError, InvalidValue}
 
 pub type Buckets =
  List(Float)
@@ -41,9 +43,8 @@ fn ffi_linear(
  count: Int,
 ) -> Result(Buckets, PrometheusError)
 
-/// Creates `Count' buckets, each `Width' wide, where the lowest
-/// bucket has an upper bound of `Start'. The returned list is meant to be
-/// used for the `buckets' key of histogram constructors options.
+/// Creates `count` buckets, each `step` wide, where the lowest bucket has an upper bound of
+/// `start`.
 ///
 /// # Examples
 ///

src/ffi_buckets.erl

@@ -1,6 +1,6 @@
 -module(ffi_buckets).
 
--import(lists,[droplast/1]).
+-import(lists, [droplast/1]).
 
 -export([
  exponential/3,

src/ffi_counter.erl

@@ -1,11 +1,11 @@
 -module(ffi_counter).
 
 -export([
- counter_new/4,
- counter_inc/4
+ create_counter/4,
+ increment_counter/4
 ]).
 
-counter_new(Registry, Name, Help, Labels) ->
+create_counter(Registry, Name, Help, Labels) ->
  try prometheus_counter:new([
  { registry, Registry },
  { name, Name },
@@ -18,7 +18,7 @@ counter_new(Registry, Name, Help, Labels) ->
  _:_ -> { error, unknown_error }
  end.
 
-counter_inc(Registry, Name, LabelValues, Value) ->
+increment_counter(Registry, Name, LabelValues, Value) ->
  try prometheus_counter:inc(Registry, Name, LabelValues, Value) of
  _ -> { ok, nil }
  catch

src/ffi_gauge.erl

@@ -1,11 +1,11 @@
 -module(ffi_gauge).
 
 -export([
- gauge_new/4,
- gauge_set/4
+ create_gauge/4,
+ set_gauge/4
 ]).
 
-gauge_new(Registry, Name, Help, Labels) ->
+create_gauge(Registry, Name, Help, Labels) ->
  try prometheus_gauge:new([
  { registry, Registry },
  { name, Name },
@@ -18,7 +18,7 @@ gauge_new(Registry, Name, Help, Labels) ->
  _:_ -> { error, unknown_error }
  end.
 
-gauge_set(Registry, Name, LabelValues, Value) ->
+set_gauge(Registry, Name, LabelValues, Value) ->
  try prometheus_gauge:set(Registry, Name, LabelValues, Value) of
  _ -> { ok, nil }
  catch

src/ffi_histogram.erl

@@ -1,11 +1,11 @@
 -module(ffi_histogram).
 
 -export([
- histogram_new/5,
- histogram_observe/4
+ create_histogram/5,
+ observe_histogram/4
 ]).
 
-histogram_new(Registry, Name, Help, Labels, Buckets) ->
+create_histogram(Registry, Name, Help, Labels, Buckets) ->
  try prometheus_histogram:new([
  { registry, Registry },
  { name, Name },
@@ -19,7 +19,7 @@ histogram_new(Registry, Name, Help, Labels, Buckets) ->
  _:_ -> { error, unknown_error }
  end.
 
-histogram_observe(Registry, Name, LabelValues, Value) ->
+observe_histogram(Registry, Name, LabelValues, Value) ->
  try prometheus_histogram:observe(Registry, Name, LabelValues, Value) of
  _ -> { ok, nil }
  catch

src/prometheus_error.gleam → src/internal/prometheus_error.gleam

@@ -1,4 +1,4 @@
-import never.{type Never}
+import internal/never.{type Never}
 
 pub type PrometheusError {
  InvalidBuckets(buckets: List(Float), reason: List(UtfCodepoint))

src/metrics/counter.gleam

@@ -1,23 +1,42 @@
+//// A counter is a cumulative metric that represents a single monotonically increasing counter whose
+//// value can only increase or be reset to zero on restart. For example, you can use a counter to
+//// represent the number of requests served, tasks completed, or errors.
+////
+//// Do not use a counter to expose a value that can decrease. For example, do not use a counter for
+//// the number of currently running processes; instead use a gauge.
+
 import gleam/int.{to_string}
-import prometheus_error.{
+import internal/prometheus_error.{
  type PrometheusError, InvalidMetricArity, MfAlreadyExists, UnknownMetric,
 }
 
-@external(erlang, "ffi_counter", "counter_new")
-fn ffi_new_counter(
+@external(erlang, "ffi_counter", "create_counter")
+fn ffi_create_counter(
  registry: String,
  name: String,
  help: String,
  labels: List(String),
 ) -> Result(Nil, PrometheusError)
 
-pub fn new_counter(
+/// Creates a new Counter metric.
+///
+/// # Examples
+///
+/// ```gleam
+/// create_counter(
+/// registry: "default",
+/// name: "http_requests_total",
+/// help: "Total number of HTTP requests",
+/// labels: [ "method", "route", "status" ],
+/// )
+/// ```
+pub fn create_counter(
  registry registry: String,
  name name: String,
  help help: String,
  labels labels: List(String),
 ) -> Result(Nil, String) {
- let result = ffi_new_counter(registry, name, help, labels)
+ let result = ffi_create_counter(registry, name, help, labels)
 
  case result {
  Ok(_) -> Ok(Nil)
@@ -26,21 +45,32 @@ pub fn new_counter(
  }
 }
 
-@external(erlang, "ffi_counter", "counter_inc")
-fn ffi_inc_counter(
+@external(erlang, "ffi_counter", "increment_counter")
+fn ffi_increment_counter(
  registry: String,
  name: String,
  labels: List(String),
  value: Int,
 ) -> Result(Nil, PrometheusError)
 
-pub fn inc_counter(
+/// Increments the Counter with the given value.
+///
+/// # Examples
+/// ```gleam
+/// increment_counter(
+/// registry: "default",
+/// name: "http_requests_total",
+/// labels: [ "GET", "/", "200" ],
+/// value: 1,
+/// )
+/// ```
+pub fn increment_counter(
  registry registry: String,
  name name: String,
  labels labels: List(String),
  value value: Int,
 ) -> Result(Nil, String) {
- let result = ffi_inc_counter(registry, name, labels, value)
+ let result = ffi_increment_counter(registry, name, labels, value)
 
  case result {
  Ok(_) -> Ok(Nil)

src/metrics/gauge.gleam

@@ -1,23 +1,41 @@
+//// A gauge is a metric that represents a single numerical value that can arbitrarily go
+//// up and down.
+////
+//// Gauges are typically used for measured values like temperatures or current memory usage, but
+//// also "counts" that can go up and down, like the number of concurrent requests.
+
 import gleam/int.{to_string}
-import prometheus_error.{
+import internal/prometheus_error.{
  type PrometheusError, InvalidMetricArity, MfAlreadyExists, UnknownMetric,
 }
 
-@external(erlang, "ffi_gauge", "gauge_new")
-fn ffi_new_gauge(
+@external(erlang, "ffi_gauge", "create_gauge")
+fn ffi_create_gauge(
  registry: String,
  name: String,
  help: String,
  labels labels: List(String),
 ) -> Result(Nil, PrometheusError)
 
-pub fn new_gauge(
+/// Creates a new Gauge metric.
+///
+/// # Examples
+///
+/// ```gleam
+/// create_gauge(
+/// registry: "default",
+/// name: "cache_size",
+/// help: "Number of items in the cache",
+/// labels: [ "cache_name" ],
+/// )
+/// ```
+pub fn create_gauge(
  registry registry: String,
  name name: String,
  help help: String,
  labels labels: List(String),
 ) -> Result(Nil, String) {
- let result = ffi_new_gauge(registry, name, help, labels)
+ let result = ffi_create_gauge(registry, name, help, labels)
 
  case result {
  Ok(_) -> Ok(Nil)
@@ -26,14 +44,25 @@ pub fn new_gauge(
  }
 }
 
-@external(erlang, "ffi_gauge", "gauge_set")
+@external(erlang, "ffi_gauge", "set_gauge")
 fn ffi_set_gauge(
  registry: String,
  name: String,
  labels: List(String),
  value: Int,
 ) -> Result(Nil, PrometheusError)
 
+/// Sets the value of the Gauge.
+///
+/// # Examples
+/// ```gleam
+/// set_gauge(
+/// registry: "default",
+/// name: "cache_size",
+/// labels: [ "image_cache" ],
+/// value: 123,
+/// )
+/// ```
 pub fn set_gauge(
  registry registry: String,
  name name: String,