Add basic doc comments for opentelemetry-http (open-telemetry#1528)

.gitignore

@@ -4,3 +4,5 @@
 **/*.rs.bk
 Cargo.lock
 /.idea/
+
+.cosine

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"

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.