refine documents

crates/shadowsocks-service/src/config.rs

@@ -987,7 +987,7 @@ pub struct Config {
     pub fast_open: bool,
     /// Set TCP Keep-Alive duration, will set both `TCP_KEEPIDLE` and `TCP_KEEPINTVL`
     ///
-    /// https://github.com/shadowsocks/shadowsocks-rust/issues/546
+    /// <https://github.com/shadowsocks/shadowsocks-rust/issues/546>
     ///
     /// If this is not set, sockets will be set with a default timeout
     pub keep_alive: Option<Duration>,

crates/shadowsocks/src/relay/tcprelay/utils.rs

@@ -256,7 +256,7 @@ where
 /// it will return a tuple of the number of bytes copied from encrypted to plain
 /// and the number of bytes copied from plain to encrypted, in that order.
 ///
-/// [`shutdown()`]: crate::io::AsyncWriteExt::shutdown
+/// [`shutdown()`]: tokio::io::AsyncWriteExt::shutdown
 ///
 /// # Errors
 ///

src/lib.rs

@@ -11,9 +11,13 @@ pub mod password;
 pub mod service;
 pub mod validator;
 
+/// Exit code when server exits unexpectly
 pub const EXIT_CODE_SERVER_EXIT_UNEXPECTEDLY: i32 = exitcode::SOFTWARE;
+/// Exit code when server aborted
 pub const EXIT_CODE_SERVER_ABORTED: i32 = exitcode::SOFTWARE;
+/// Exit code when loading configuration from file fails
 pub const EXIT_CODE_LOAD_CONFIG_FAILURE: i32 = exitcode::CONFIG;
+/// Exit code when loading ACL from file fails
 pub const EXIT_CODE_LOAD_ACL_FAILURE: i32 = exitcode::CONFIG;
 
 /// Build timestamp in UTC

src/logging/mod.rs

@@ -1,4 +1,4 @@
-//! Loggin facilities
+//! Logging facilities
 
 use std::{env, path::Path};
 
@@ -10,6 +10,7 @@ use log4rs::{
     encode::pattern::PatternEncoder,
 };
 
+/// Initialize logger ([log4rs](https://crates.io/crates/log4rs)) from yaml configuration file
 pub fn init_with_file<P>(path: P)
 where
     P: AsRef<Path>,
@@ -17,6 +18,7 @@ where
     log4rs::init_file(path, Default::default()).expect("init logging with file");
 }
 
+/// Initialize logger with default configuration
 pub fn init_with_config(bin_name: &str, matches: &ArgMatches) {
     let mut debug_level = matches.occurrences_of("VERBOSE");
     if debug_level == 0 {

src/monitor/other.rs

@@ -1,6 +1,9 @@
 use futures;
 use std::io;
 
+/// Create a monitor future for signals
+///
+/// This is a dummy future in the current platform.
 pub async fn create_signal_monitor() -> io::Result<()> {
     // FIXME: What can I do ...
     // Blocks forever

src/monitor/unix.rs

@@ -3,6 +3,9 @@ use log::info;
 use std::io;
 use tokio::signal::unix::{signal, SignalKind};
 
+/// Create a monitor future for signals
+///
+/// It will exit when received `SIGTERM` or `SIGINT`.
 pub async fn create_signal_monitor() -> io::Result<()> {
     // Future resolving to two signal streams. Can fail if setting up signal monitoring fails
     let mut sigterm = signal(SignalKind::terminate())?;

src/monitor/windows.rs

@@ -2,6 +2,9 @@ use log::info;
 use std::io;
 use tokio::signal::ctrl_c;
 
+/// Create a monitor future for signals
+///
+/// It will exit when received Ctrl-C.
 pub async fn create_signal_monitor() -> io::Result<()> {
     let _ = ctrl_c().await;
     info!("received CTRL-C, exiting");

src/service/manager.rs

@@ -1,3 +1,5 @@
+//! Server Manager launchers
+
 use std::{net::IpAddr, path::PathBuf, process, time::Duration};
 
 use clap::{clap_app, App, Arg, ArgMatches, ErrorKind as ClapErrorKind};

src/service/server.rs

@@ -1,11 +1,4 @@
-//! This is a binary running in the server environment
-//!
-//! You have to provide all needed configuration attributes via command line parameters,
-//! or you could specify a configuration file. The format of configuration file is defined
-//! in mod `config`.
-//!
-//! *It should be notice that the extended configuration file is not suitable for the server
-//! side.*
+//! Server launchers
 
 use std::{net::IpAddr, path::PathBuf, process, time::Duration};
 
@@ -29,6 +22,7 @@ use shadowsocks_service::{
 use crate::logging;
 use crate::{monitor, validator};
 
+/// Defines command line options
 pub fn define_command_line_options<'a, 'b>(app: App<'a, 'b>) -> App<'a, 'b> {
     let mut app = clap_app!(@app (app)
         (@arg CONFIG: -c --config +takes_value "Shadowsocks configuration file (https://shadowsocks.org/en/config/quick-guide.html)")