From 49f1be6164c104d1e676f357d2f50271ac6e5938 Mon Sep 17 00:00:00 2001
From: Cijo Thomas <cijo.thomas@gmail.com>
Date: Tue, 13 Feb 2024 21:45:19 -0800
Subject: [PATCH] Add basic doc comments for opentelemetry-http (#1528)

---
 .gitignore                    |  2 ++
 opentelemetry-http/Cargo.toml |  4 ++--
 opentelemetry-http/src/lib.rs | 12 +++++++++++-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 9906874e2d..02a0111fdb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,5 @@
 **/*.rs.bk
 Cargo.lock
 /.idea/
+
+.cosine
\ No newline at end of file
diff --git a/opentelemetry-http/Cargo.toml b/opentelemetry-http/Cargo.toml
index 4429d148a7..5263e32481 100644
--- a/opentelemetry-http/Cargo.toml
+++ b/opentelemetry-http/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
 name = "opentelemetry-http"
 version = "0.10.0"
-description = "Helper implementations for exchange of traces and metrics over HTTP"
+description = "Helper implementations for sending HTTP requests. Uses include propagating and extracting context over http, exporting telemetry, requesting sampling strategies."
 homepage = "https://github.com/open-telemetry/opentelemetry-rust"
 repository = "https://github.com/open-telemetry/opentelemetry-rust"
-keywords = ["opentelemetry", "tracing", "metrics"]
+keywords = ["opentelemetry", "tracing", "context", "propagation"]
 license = "Apache-2.0"
 edition = "2021"
 rust-version = "1.65"
diff --git a/opentelemetry-http/src/lib.rs b/opentelemetry-http/src/lib.rs
index 67d2c7b11a..70acd11ff4 100644
--- a/opentelemetry-http/src/lib.rs
+++ b/opentelemetry-http/src/lib.rs
@@ -7,6 +7,10 @@ pub use bytes::Bytes;
 pub use http::{Request, Response};
 use opentelemetry::propagation::{Extractor, Injector};
 
+/// Helper for injecting headers into HTTP Requests. This is used for OpenTelemetry context
+/// propagation over HTTP.
+/// See [this](https://github.com/open-telemetry/opentelemetry-rust/blob/main/examples/tracing-http-propagator/README.md)
+/// for example usage.
 pub struct HeaderInjector<'a>(pub &'a mut http::HeaderMap);
 
 impl<'a> Injector for HeaderInjector<'a> {
@@ -20,6 +24,10 @@ impl<'a> Injector for HeaderInjector<'a> {
     }
 }
 
+/// Helper for extracting headers from HTTP Requests. This is used for OpenTelemetry context
+/// propagation over HTTP.
+/// See [this](https://github.com/open-telemetry/opentelemetry-rust/blob/main/examples/tracing-http-propagator/README.md)
+/// for example usage.
 pub struct HeaderExtractor<'a>(pub &'a http::HeaderMap);
 
 impl<'a> Extractor for HeaderExtractor<'a> {
@@ -39,7 +47,9 @@ impl<'a> Extractor for HeaderExtractor<'a> {
 
 pub type HttpError = Box<dyn std::error::Error + Send + Sync + 'static>;
 
-/// A minimal interface necessary for export spans over HTTP.
+/// A minimal interface necessary for sending requests over HTTP.
+/// Used primarily for exporting telemetry over HTTP. Also used for fetching
+/// sampling strategies for JaegerRemoteSampler
 ///
 /// Users sometime choose HTTP clients that relay on a certain async runtime. This trait allows
 /// users to bring their choice of HTTP client.