Top level module docs for swimos.

Author: horned-sphere

swimos/Cargo.toml

@@ -5,9 +5,9 @@ authors = ["Swim Inc. developers info@swim.ai"]
 edition = "2021"
 
 [features]
-default = ["agent"]
+default = []
 all = ["server", "agent", "json"]
-server = ["dep:swimos_server_app"]
+server = ["dep:swimos_server_app", "dep:swimos_remote"]
 agent = ["dep:swimos_agent", "dep:swimos_agent_derive"]
 json = ["agent", "swimos_agent/json"]
 
@@ -19,7 +19,7 @@ swimos_recon = { path = "../api/formats/swimos_recon" }
 swimos_server_app = { path = "../server/swimos_server_app", optional = true }
 swimos_agent = { path = "../server/swimos_agent", optional = true }
 swimos_agent_derive = { path = "../server/swimos_agent_derive", optional = true }
-swimos_remote = { path = "../runtime/swimos_remote" }
+swimos_remote = { path = "../runtime/swimos_remote", optional = true}
 
 [dev-dependencies]
 parking_lot = { workspace = true }

swimos/src/lib.rs

@@ -15,16 +15,17 @@
 #[doc(inline)]
 pub use swimos_model as model;
 
-/// Defines the low level API for implementing Swim agents.
+/// Defines the low level API for implementing Swim applications.
 pub mod api {
     pub use swimos_api::agent::{Agent, DownlinkKind, UplinkKind};
     pub use swimos_utilities::handlers::NoHandler;
 
+    /// Address types to refer to the location of agent instances.
     pub mod address {
         pub use swimos_api::address::{Address, RelativeAddress};
     }
 
-    /// Error
+    /// Error types produced by implementations of the implementations of the Swim API.
     pub mod error {
         pub use swimos_api::error::{
             AgentInitError, AgentRuntimeError, AgentTaskError, DownlinkFailureReason,
@@ -33,6 +34,7 @@ pub mod api {
         };
     }
 
+    /// Defines the interface for defining Swim agent implementations.
     pub mod agent {
         pub use swimos_api::agent::{
             AgentConfig, AgentContext, AgentInitResult, AgentTask, BoxAgent, DownlinkKind,
@@ -44,41 +46,54 @@ pub mod api {
     }
 }
 
-pub mod utilities {
+/// Retry strategies for processes that could fail.
+pub mod retry {
     pub use swimos_utilities::future::{Quantity, RetryStrategy};
 }
 
+/// Descriptions of agent routes and patterns for matching against them.
 pub mod route {
     pub use swimos_utilities::routing::RouteUri;
     pub use swimos_utilities::routing::{ApplyError, ParseError, RoutePattern, UnapplyError};
 }
 
+/// Channels and error types for communication between the SwimOS runtime and Swim agents.
 pub mod io {
+
+    /// Bidirectional byte channels used to communicate between the SwimOS runtime and Swim agents
+    /// instances.
     pub mod channels {
         pub use swimos_utilities::byte_channel::{
             are_connected, byte_channel, ByteReader, ByteWriter,
         };
     }
+
+    /// Error types that can be produced when serializing and deserializing messages within the SwimOS
+    /// runtime.
     pub mod errors {
         pub use swimos_api::error::{FrameIoError, InvalidFrame};
         pub use swimos_recon::parser::{AsyncParseError, ParseError};
     }
+
 }
 
+/// The core Swim server application runtime.
 #[cfg(feature = "server")]
 pub mod server {
     pub use swimos_server_app::{
         BoxServer, DeflateConfig, IntrospectionConfig, RemoteConnectionsConfig, Server,
         ServerBuilder, ServerHandle, WindowBits,
     };
 
+    /// Configuration for TLS support in the server.
     pub mod tls {
         pub use swimos_remote::tls::{
             CertChain, CertFormat, CertificateFile, ClientConfig, PrivateKey, ServerConfig,
             TlsConfig,
         };
     }
 
+    /// Error types that can be produced when initializing and executing the server.
     pub mod errors {
         pub use swimos_remote::tls::TlsError;
         pub use swimos_remote::ConnectionError;