From 66e93a53fea65dffe3f703f2ae96f01d0f3fae6f Mon Sep 17 00:00:00 2001
From: MOZGIII <mike-n@narod.ru>
Date: Sat, 3 Feb 2024 03:33:09 -0300
Subject: [PATCH] Basic documentation to the xwt-web-sys and xwt-wtransport
 (#78)

---
 crates/xwt-web-sys/src/error.rs     |  3 +++
 crates/xwt-web-sys/src/lib.rs       | 23 ++++++++++++++++++++++-
 crates/xwt-wtransport/src/lib.rs    |  2 +-
 crates/xwt-wtransport/src/types.rs  |  5 +++++
 crates/xwt-wtransport/tests/test.rs |  1 -
 5 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/crates/xwt-web-sys/src/error.rs b/crates/xwt-web-sys/src/error.rs
index 17dac71..d3502ad 100644
--- a/crates/xwt-web-sys/src/error.rs
+++ b/crates/xwt-web-sys/src/error.rs
@@ -1,3 +1,6 @@
+//! Error type definition.
+
+/// A generic error encapsulating a JS-land value.
 #[derive(Debug)]
 pub struct Error(pub wasm_bindgen::JsValue);
 
diff --git a/crates/xwt-web-sys/src/lib.rs b/crates/xwt-web-sys/src/lib.rs
index a813e29..f62ef60 100644
--- a/crates/xwt-web-sys/src/lib.rs
+++ b/crates/xwt-web-sys/src/lib.rs
@@ -7,7 +7,6 @@
     doc = "The `web_sys`-powered implementation of `xwt_core`."
 )]
 #![cfg(target_family = "wasm")]
-#![allow(missing_docs, clippy::missing_docs_in_private_items)]
 
 use std::rc::Rc;
 
@@ -17,8 +16,13 @@ mod error;
 
 pub use error::*;
 
+/// An endpoint for the xwt.
+///
+/// Internally holds the connection options and can create
+/// a new `WebTransport` object on the "web" side on a connection request.
 #[derive(Debug, Clone, Default)]
 pub struct Endpoint {
+    /// The options to use to create the `WebTransport`s.
     pub options: web_sys::WebTransportOptions,
 }
 
@@ -46,10 +50,16 @@ impl xwt_core::traits::EndpointConnect for Endpoint {
     }
 }
 
+/// Connection hold the [`web_sys::WebTransport`] and is responsible for
+/// providing access to the Web API of WebTransport in a way that is portable.
+/// It also holds handles to the datagram reader and writer.
 #[derive(Debug)]
 pub struct Connection {
+    /// The WebTransport instance.
     pub transport: Rc<web_sys::WebTransport>,
+    /// The datagram reader.
     pub datagram_readable_stream_reader: web_sys::ReadableStreamDefaultReader,
+    /// The datagram writer.
     pub datagram_writable_stream_writer: web_sys::WritableStreamDefaultWriter,
 }
 
@@ -58,18 +68,27 @@ impl xwt_core::traits::Streams for Connection {
     type RecvStream = RecvStream;
 }
 
+/// Send the data into a WebTransport stream.
 pub struct SendStream {
+    /// The WebTransport instance.
     pub transport: Rc<web_sys::WebTransport>,
+    /// The handle to the stream to write to.
     pub stream: web_sys::WebTransportSendStream,
+    /// A writer to conduct the operation.
     pub writer: web_sys_async_io::Writer,
 }
 
+/// Recv the data from a WebTransport stream.
 pub struct RecvStream {
+    /// The WebTransport instance.
     pub transport: Rc<web_sys::WebTransport>,
+    /// The handle to the stream to read from.
     pub stream: web_sys::WebTransportReceiveStream,
+    /// A reader to conduct the operation.
     pub reader: web_sys_async_io::Reader,
 }
 
+/// Open a reader for the given stream and create a [`RecvStream`].
 fn wrap_recv_stream(
     transport: &Rc<web_sys::WebTransport>,
     stream: web_sys::WebTransportReceiveStream,
@@ -86,6 +105,7 @@ fn wrap_recv_stream(
     }
 }
 
+/// Open a writer for the given stream and create a [`SendStream`].
 fn wrap_send_stream(
     transport: &Rc<web_sys::WebTransport>,
     stream: web_sys::WebTransportSendStream,
@@ -99,6 +119,7 @@ fn wrap_send_stream(
     }
 }
 
+/// Take a bidi stream and wrap a reader and writer for it.
 fn wrap_bi_stream(
     transport: &Rc<web_sys::WebTransport>,
     stream: web_sys::WebTransportBidirectionalStream,
diff --git a/crates/xwt-wtransport/src/lib.rs b/crates/xwt-wtransport/src/lib.rs
index 9419f60..e40ec01 100644
--- a/crates/xwt-wtransport/src/lib.rs
+++ b/crates/xwt-wtransport/src/lib.rs
@@ -7,7 +7,6 @@
     doc = "The `wtransport`-powered implementation of `xwt_core`."
 )]
 #![cfg(not(target_family = "wasm"))]
-#![allow(missing_docs, clippy::missing_docs_in_private_items)]
 
 use xwt_core::async_trait;
 
@@ -73,6 +72,7 @@ impl xwt_core::traits::Streams for Connection {
     type RecvStream = RecvStream;
 }
 
+/// Take a pair of stream ends and wrap into our newtypes.
 fn map_streams(
     streams: (wtransport::SendStream, wtransport::RecvStream),
 ) -> (SendStream, RecvStream) {
diff --git a/crates/xwt-wtransport/src/types.rs b/crates/xwt-wtransport/src/types.rs
index 96d5d45..a942299 100644
--- a/crates/xwt-wtransport/src/types.rs
+++ b/crates/xwt-wtransport/src/types.rs
@@ -1,5 +1,9 @@
+//! Newtype definitions.
+
+/// Create a newtype wrapper for a given type.
 macro_rules! newtype {
     ($name:ident => $wrapped_type:path) => {
+        /// A [`$wrapped_type`] newtype.
         pub struct $name(pub $wrapped_type);
 
         impl std::fmt::Debug for $name {
@@ -9,6 +13,7 @@ macro_rules! newtype {
         }
     };
     ($name:ident < $($generics:tt),* > => $wrapped_type:path) => {
+        /// A [`$wrapped_type`] newtype.
         pub struct $name<$($generics)*>(pub $wrapped_type);
 
         impl<$($generics)*> std::fmt::Debug for $name<$($generics)*> {
diff --git a/crates/xwt-wtransport/tests/test.rs b/crates/xwt-wtransport/tests/test.rs
index 5484170..3666341 100644
--- a/crates/xwt-wtransport/tests/test.rs
+++ b/crates/xwt-wtransport/tests/test.rs
@@ -1,6 +1,5 @@
 #![cfg(not(target_family = "wasm"))]
 #![feature(once_cell_try)]
-#![allow(missing_docs, clippy::missing_docs_in_private_items)]
 
 fn setup() -> color_eyre::eyre::Result<()> {
     static INIT: std::sync::OnceLock<()> = std::sync::OnceLock::new();