From 1c76c52e8b1e14aa187db9229183894bd43ebaa4 Mon Sep 17 00:00:00 2001
From: Maaz Ahmed <maaz.a@subcom.tech>
Date: Thu, 14 Dec 2023 14:12:55 +0530
Subject: [PATCH] doc: update and add missing docs
---
src/lib.rs | 25 +++++++++++++++++++++----
src/query/mod.rs | 8 ++++++++
2 files changed, 29 insertions(+), 4 deletions(-)
diff --git a/src/lib.rs b/src/lib.rs
index 67dcae1..baaef71 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,4 @@
-//! A wrapper around prometheus_http_query with additional features for ease of use
-//!
-//! All HTTP requests are made using the `reqwest` client
+#![doc = include_str!("../README.md")]
pub mod query;
@@ -55,13 +53,18 @@ impl QueryManager {
self
}
- /// Set HTTP method to use to send queries to the server
+ /// Set HTTP method to use to send queries to the server (default: `Get`)
pub fn method(&mut self, method: Method) -> &mut Self {
self.method = method;
self
}
/// Send a query to the Prometheus server and retreived deserialized data
+ ///
+ /// This method accepts any type that implements the `IntoQuery` trait.
+ /// The trait is implemented for `&str`, `String`, `&String`, and __mquery's__
+ /// internal types such as [`query::Metric`], [`query::Scalar`] and others that result
+ /// from the query builder API.
pub async fn query<Q: IntoQuery>(&self, query: Q) -> Result<PromqlResult, Error> {
let mut builder = self.client.query(query.into_query().as_ref());
if let Some((name, val)) = self.auth.get_header() {
@@ -77,6 +80,11 @@ impl QueryManager {
}
/// Send a ranged query to the Prometheus server and retreived deserialized data
+ ///
+ /// This method accepts any type that implements the `IntoQuery` trait.
+ /// The trait is implemented for `&str`, `String`, `&String`, and __mquery's__
+ /// internal types such as [`query::Metric`], [`query::Scalar`] and others that result
+ /// from the query builder API.
pub async fn query_range<Q: IntoQuery>(
&self,
query: Q,
@@ -101,6 +109,9 @@ impl QueryManager {
}
// TODO: Add support for basic auth as well
+/// Authentication method
+///
+/// Used in [`QueryManager::auth`] to set the authentication type
#[derive(Default, Clone, Debug)]
pub enum Auth {
#[default]
@@ -125,6 +136,10 @@ impl Auth {
}
}
+/// HTTP method to use to send queries
+///
+/// This is used by the [`QueryManager::method`] method to set the HTTP
+/// method used to send queries to the server.
#[derive(Clone, Copy, Debug, Default)]
pub enum Method {
#[default]
@@ -132,6 +147,8 @@ pub enum Method {
Post,
}
+// Private trait used to seal other traits to disallow users from implementing
+// them directly
pub(crate) mod seal {
pub(crate) trait Sealed {}
}
diff --git a/src/query/mod.rs b/src/query/mod.rs
index 24ce386..3bbdc43 100644
--- a/src/query/mod.rs
+++ b/src/query/mod.rs
@@ -1,3 +1,8 @@
+//! The query builder API
+//!
+//! [`Metric`] and [`Scalar`] are the basic types used for building queries.
+//! For building complex queries involving operators, see module [`ops`].
+
use std::fmt::Display;
use crate::seal::Sealed;
@@ -50,6 +55,9 @@ pub struct Metric<'a> {
impl<'a> Metric<'a> {
/// Create a new metric with a metric name (for example `total_http_requests`)
+ ///
+ /// A metric can be constructed with an empty string as well, however, it's important to
+ /// have at least one label matcher present for the query to be valid.
pub fn new(name: &'a str) -> Self {
Self {
name,
--
GitLab