Add crate docs for ttrpc-rust

- Add docs.
- Display all features in docs.
- Make the intermediate-module compiled private.

Signed-off-by: Tim Zhang <[email protected]>

Author: Tim-Zhang

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ttrpc"
-version = "0.4.0"
+version = "0.4.1"
 authors = ["The AntFin Kata Team <[email protected]>"]
 edition = "2018"
 license = "Apache-2.0"
@@ -32,3 +32,6 @@ protobuf-codec = ["protobuf"]
 async = []
 sync = []
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

src/asynchronous/client.rs

@@ -29,6 +29,7 @@ type RequestReceiver = Receiver<(Vec<u8>, Sender<Result<Vec<u8>>>)>;
 type ResponseSender = Sender<Result<Vec<u8>>>;
 type ResponseReceiver = Receiver<Result<Vec<u8>>>;
 
+/// A ttrpc Client (async).
 #[derive(Clone)]
 pub struct Client {
     req_tx: RequestSender,

src/asynchronous/mod.rs

@@ -3,12 +3,17 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+//! Server and client in async mode.
+
 pub mod client;
 pub mod server;
 pub mod stream;
 #[macro_use]
 pub mod utils;
 
+#[doc(inline)]
 pub use crate::r#async::client::Client;
+#[doc(inline)]
 pub use crate::r#async::server::Server;
+#[doc(inline)]
 pub use crate::r#async::utils::{convert_response_to_buf, MethodHandler, TtrpcContext};

src/asynchronous/server.rs

@@ -28,6 +28,7 @@ use tokio::{
 };
 use tokio_vsock::VsockListener;
 
+/// A ttrpc Server (async).
 pub struct Server {
     listeners: Vec<RawFd>,
     methods: Arc<HashMap<String, Box<dyn MethodHandler + Send + Sync>>>,

src/asynchronous/utils.rs

@@ -11,6 +11,7 @@ use protobuf::Message;
 use std::os::unix::io::{FromRawFd, RawFd};
 use tokio::net::UnixStream;
 
+/// Handle request in async mode.
 #[macro_export]
 macro_rules! async_request_handler {
     ($class: ident, $ctx: ident, $req: ident, $server: ident, $req_type: ident, $req_fn: ident) => {
@@ -49,6 +50,7 @@ macro_rules! async_request_handler {
     };
 }
 
+/// Send request through async client.
 #[macro_export]
 macro_rules! async_client_request {
     ($self: ident, $req: ident, $timeout_nano: ident, $server: expr, $method: expr, $cres: ident) => {
@@ -74,11 +76,13 @@ macro_rules! async_client_request {
     };
 }
 
+/// Trait that implements handler which is a proxy to the desired method (async).
 #[async_trait]
 pub trait MethodHandler {
     async fn handler(&self, ctx: TtrpcContext, req: Request) -> Result<(u32, Vec<u8>)>;
 }
 
+/// The context of ttrpc (async).
 #[derive(Debug)]
 pub struct TtrpcContext {
     pub fd: std::os::unix::io::RawFd,

src/common.rs

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+//! Common functions and macros.
+
 #![allow(unused_macros)]
 
 use crate::error::{Error, Result};
@@ -17,6 +19,7 @@ pub enum Domain {
     Vsock,
 }
 
+/// Message header of ttrpc.
 #[derive(Default, Debug)]
 pub struct MessageHeader {
     pub length: u32,
@@ -102,6 +105,8 @@ macro_rules! cfg_sync {
     ($($item:item)*) => {
         $(
             #[cfg(feature = "sync")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "sync")))]
+            #[doc(inline)]
             $item
         )*
     }
@@ -111,6 +116,8 @@ macro_rules! cfg_async {
     ($($item:item)*) => {
         $(
             #[cfg(feature = "async")]
+            #[cfg_attr(docsrs, doc(cfg(feature = "async")))]
+            #[doc(inline)]
             $item
         )*
     }

src/error.rs

@@ -12,18 +12,23 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Error and Result of ttrpc and relevant functions, macros.
+
 use crate::ttrpc::{Code, Status};
 use std::result;
 
+/// The error type for ttrpc.
 #[derive(Debug)]
 pub enum Error {
     Socket(String),
     RpcStatus(Status),
     Others(String),
 }
 
+/// A specialized Result type for ttrpc.
 pub type Result<T> = result::Result<T, Error>;
 
+/// Get ttrpc::Status from ttrpc::Code and a message.
 pub fn get_status(c: Code, msg: String) -> Status {
     let mut status = Status::new();
     status.set_code(c);
@@ -57,6 +62,7 @@ macro_rules! err_to_Others {
     };
 }
 
+/// Convert to ttrpc::Error::Others.
 #[macro_export]
 macro_rules! Err_to_Others {
     ($e: ident, $s: expr) => {

src/lib.rs

@@ -12,6 +12,20 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! ttrpc-rust is a **non-core** subproject of containerd
+//!
+//! `ttrpc-rust` is the Rust version of [ttrpc](https://github.com/containerd/ttrpc). [ttrpc](https://github.com/containerd/ttrpc) is GRPC for low-memory environments.
+//!
+//! Example:
+//!
+//! Check [this](https://github.com/containerd/ttrpc-rust/tree/master/example)
+//!
+//! # Feature flags
+//!
+//! - `async`: Enables async server and client.
+//! - `sync`: Enables traditional sync server and client (default enabled).
+//! - `protobuf-codec`: Includes rust-protobuf (default enabled).
+
 #[macro_use]
 extern crate log;
 
@@ -20,13 +34,17 @@ pub mod error;
 #[macro_use]
 pub mod common;
 #[allow(clippy::type_complexity, clippy::too_many_arguments)]
-pub mod compiled {
+mod compiled {
     include!(concat!(env!("OUT_DIR"), "/mod.rs"));
 }
+#[doc(inline)]
 pub use compiled::ttrpc;
 
+#[doc(inline)]
 pub use crate::common::MessageHeader;
+#[doc(inline)]
 pub use crate::error::{get_status, Error, Result};
+#[doc(inline)]
 pub use crate::ttrpc::{Code, Request, Response, Status};
 
 cfg_sync! {

src/sync/client.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Sync client of ttrpc.
+
 use nix::sys::select::*;
 use nix::sys::socket::*;
 use nix::unistd::close;
@@ -31,6 +33,7 @@ use crate::MessageHeader;
 type Sender = mpsc::Sender<(Vec<u8>, mpsc::SyncSender<Result<Vec<u8>>>)>;
 type Receiver = mpsc::Receiver<(Vec<u8>, mpsc::SyncSender<Result<Vec<u8>>>)>;
 
+/// A ttrpc Client (sync).
 #[derive(Clone)]
 pub struct Client {
     fd: RawFd,

src/sync/mod.rs

@@ -3,6 +3,8 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
+//! Server and Client in sync mode.
+
 #[macro_use]
 pub mod channel;
 pub mod client;