Add document

README.md

@@ -1,8 +1,12 @@
-# Tansa: LAN service discovery over multicast
+# Tansa: LAN service discovery over IPv6 multicast
 
 [![codecov](https://codecov.io/github/seamlik/tansa/graph/badge.svg?token=AH6YGZOMJM)](https://codecov.io/github/seamlik/tansa)
 
-Work in progress.
+This project is an opinionated solution of multicast discovery.
+Written in pure Rust, it is [cross-platform](https://doc.rust-lang.org/nightly/rustc/platform-support.html) and is suitable to be a unified and portable solution for an application planning to span all major devices like laptops, smartphones and more.
+
+This project offers both a crate and a CLI application.
+However, I will not publish it to any public registry since it is highly experimental.
 
 ## Project name meaning
 

main/src/lib.rs

@@ -1,3 +1,33 @@
+//! LAN service discovery over IPv6 multicast.
+//!
+//! # General steps of usage
+//!
+//! Like traditional applications operating in the local IP.
+//! When providing your service through network sockets, you must agree on a fixed port.
+//! However, when using this crate, that fixed port is called "discovery port."
+//! Your application can bind to a wildcard socket (like `0.0.0.0:0`),
+//! after which the operating system will give you a concrete random port known as "service port".
+//! You will then use [serve] to publish the service port to the discovery port.
+//! Other devices within the same LAN can use [scan] to discover it.
+//!
+//! # Caveat
+//!
+//! IPv4, both in discovery and application, is unsupported.
+//! This simplifies the implementation of this crate.
+//! Given that we are only talking about LAN which is more likely to support IPv6,
+//! it should not be a major limitation.
+//!
+//! # Frequently used terms
+//!
+//! * Discovery IP: The multicast IPv6 acting as rendezvous for service information.
+//!   It is hardcoded in this crate.
+//! * Discovery port: The port on the discovery IP acting as rendezvous for service information.
+//!   Each application must use its own discovery port.
+//! * Service port: The port to connect to your application.
+//!   It is usually randomly allocated by the operating system.
+//! * Service information: Necessary information you need to connect to a service you discoverd.
+//!   Usually contains the socket address accessible within the LAN you connect.
+
 mod multicast;
 mod packet;
 mod response_collector;

main/src/scanner.rs

@@ -17,11 +17,13 @@ use tansa_protocol::MulticastPacket;
 use tansa_protocol::Request;
 use thiserror::Error;
 
+/// Service information discovered during [scan].
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub struct Service {
     pub address: SocketAddrV6,
 }
 
+/// Scans for all services being published to `discovery_port`.
 pub fn scan(discovery_port: u16) -> impl Stream<Item = Result<Service, ScanError>> {
     GrpcResponseCollector::new()
         .err_into()
@@ -107,6 +109,7 @@ fn extract_service(packet: MulticastPacket, mut address: SocketAddrV6) -> anyhow
     Ok(Service { address })
 }
 
+/// Error during [scan].
 #[derive(Error, Debug)]
 pub enum ScanError {
     #[error("Invalid discovery port")]

main/src/server.rs

@@ -13,6 +13,7 @@ use tansa_protocol::MulticastPacket;
 use tansa_protocol::Response;
 use thiserror::Error;
 
+/// Error during [serve].
 #[derive(Error, Debug)]
 pub enum ServeError {
     #[error("Invalid discovery port")]
@@ -22,6 +23,7 @@ pub enum ServeError {
     NetworkIo(#[from] std::io::Error),
 }
 
+/// Publishes the service provided at `service_port` to `discovery port`.
 pub async fn serve(discovery_port: u16, service_port: u16) -> Result<(), ServeError> {
     serve_internal(
         discovery_port,