Add more documentation.

fleck/src/fleck_core.rs

@@ -1,3 +1,13 @@
+//! This module contains the core services (and channel definitions) that make up a `fleck` node.
+//! 
+//! Currently, the following externally-accessible services are added by default:
+//! - [`msg::MessageService`]
+//! - [`node::NodeService`]
+//! - [`discovery::LocalDiscovery`]
+//! - [`peer::PeerService`]
+//! - [`crypto::EncryptionService`]
+
+
 pub mod crypto;
 pub mod discovery;
 pub mod io;
@@ -41,6 +51,7 @@ pub type MinorTickChannel = (channel_tags::MinorTickTag, ());
 /// Major ticks (several times per minute): for retries, cleanup tasks, periodic queries, etc
 pub type MajorTickChannel = (channel_tags::MajorTickTag, ());
 
+/// Initial bootstrapping service to create the other core services.
 #[derive(Default)]
 pub struct CoreInitService {}
 
@@ -66,6 +77,7 @@ impl crate::service::DefaultService for CoreInitService {
         api.add_service::<node::NodeService>();
         api.add_service::<discovery::DiscoveryService>();
         api.add_service::<discovery::LocalDiscovery>();
+        api.add_service::<discovery::PeerDiscovery>();
         api.add_service::<peer::PeerService>();
         api.add_service::<crypto::SignPacket>();
         api.add_service::<crypto::EncryptionService>();

fleck/src/fleck_core/discovery.rs

@@ -16,7 +16,7 @@ impl fleck_core::msg::MessageParams for DiscoveryMsg {
 }
 
 /// Handles incoming DiscoveryMsgs
-pub struct DiscoveryService {
+pub(crate) struct DiscoveryService {
     api: Rc<crate::API>,
 }
 

fleck/src/fleck_core/node.rs

@@ -196,6 +196,7 @@ impl NodeService {
                 None => {
                     // the interesting case, it's a new node!
                     // TODO: send them a request for their public key
+                    log::warn!("incoming message from unknown source; peer is {:?}", &peer);
                 }
             }
         }

fleck/src/fleck_core/peer.rs

@@ -1,9 +1,12 @@
-//! Peer: someone we can communicate with directly
+//! A peer is a communication address abstraction. There may or may not be someone (still) listening there.
+//!
+//!
 
 use std::{cell::Cell, rc::Rc};
 
 use crate::prelude::*;
 
+#[derive(Debug)]
 pub(crate) enum PeerAddress {
     Stream,
     Udp(std::net::SocketAddr),
@@ -38,10 +41,14 @@ impl PeerData {
 
 impl std::fmt::Debug for PeerData {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("PeerData {}")
+        f.write_fmt(format_args!("PeerData {{ address_info: {:?} }}", self.address_info))
     }
 }
 
+/// The primary peer representation as used in `fleck`.
+///
+/// This is deliberately an opaque type, to encourage writing transport-agnostic code as much as
+/// possible. Treat as a black box unless you really have to not.
 #[derive(Clone, Debug)]
 pub struct Peer {
     pub(crate) data: Rc<PeerData>,

fleck/src/lib.rs

@@ -1,3 +1,28 @@
+//! `fleck` is a library to for peer-to-peer communications in a distributed system.
+//!
+//! The core concept is that any program that wants to talk with other instances of itself (or
+//! compatible programs) can use `fleck`, and as much of the usual development overhead (network
+//! event loop, peer identity verification, packet encryption and forwarding, NAT punchthrough,
+//! etc) is handled within the library, in a way that the program need not care about.
+//!
+//! ### Library structure
+//! `fleck` is structured with a 'global' [`API`] instance, where any node-wide
+//! global state is stored. The [`API`] instance stores a collection of
+//! [`Channel`](service/event/struct.Channel.html) and [`Service`](service/trait.Service.html)
+//! instances. Services listen on specific channels, and events are sent to channels to be handled.
+//! 
+//! For example, the [`NodeService`](fleck_core/node/struct.NodeService.html) will send events on a
+//! channel whenever a new node joins the `fleck` network. To reduce shared global state, channels
+//! are identified by a static [`ChannelSpec`](service/event/trait.ChannelSpec.html) type, which is
+//! usually a tuple of two or three other static types that allow distinguishing between e.g.
+//! [messages of different types being received](fleck_core/msg/type.MessageChannel.html), or
+//! [coarse](fleck_core/type.MajorTickChannel.html) and
+//! [fine](fleck_core/type.MinorTickChannel.html) tick timers.
+//!
+//! See the documentation for the [`fleck_core`] module to see the core
+//! services and channels that make up a standard `fleck` node.
+
+
 use std::rc::Rc;
 
 pub mod fleck_core;

fleck/src/service.rs

@@ -4,7 +4,7 @@ use std::collections::HashMap;
 use std::ops::Deref;
 use std::rc::{Rc, Weak};
 
-pub(crate) mod event;
+pub mod event;
 
 pub use event::ChannelSpec;