Add docstring to functions

Author: dudik

src/main.rs

@@ -19,6 +19,10 @@ enum InitType {
     Update
 }
 
+/// Handles communication with clients connecting to the server.
+///
+/// * `stream` - Data stream representing the connection between the client and the server.
+/// * `blocker` - Pointer to the Engine struct which should be used for decision making.
 fn handle_client(mut stream: UnixStream, mut blocker: Arc<Engine>) {
     let reader = BufReader::new(stream.try_clone().unwrap());
     for line in reader.lines() {
@@ -79,6 +83,12 @@ fn handle_client(mut stream: UnixStream, mut blocker: Arc<Engine>) {
     }
 }
 
+/// Updates the specified filter list, returns the URL with the expiration timestamp.
+/// 
+/// The timestamp won't be appended if the filter list doesn't contain the `Expired` field.
+///
+/// * `url` - URL of the filter list that should be updated.
+/// * `lists_dir` - Directory path where the filter list should be saved.
 fn update_list(url: &str, lists_dir: &str) -> String {
     let filename = url.split('/').last().unwrap();
     let res = attohttpc::get(&url).send().unwrap();
@@ -107,6 +117,15 @@ fn update_list(url: &str, lists_dir: &str) -> String {
     return url.to_string();
 }
 
+/// Parses the URL file and returns a boolean stating if the configuration was updated.
+/// 
+/// Process every URL in the `urls_file`. If the file doesn't exist, it will be created.
+///
+/// * `urls_file` - Path of the URL file.
+/// * `lists_dir` - Directory path where the filter lists should be saved.
+/// * `force_update` - Boolean which when set to true will forcefully update every filter list
+/// present in the URL file, even though it doesn't have to be updated (based on the 'Expires'
+/// field)
 fn parse_urls(urls_file: &str, lists_dir: &str, force_update: bool) -> bool {
     fs::create_dir_all(&lists_dir).unwrap();
     let mut updated = false;
@@ -147,6 +166,16 @@ fn parse_urls(urls_file: &str, lists_dir: &str, force_update: bool) -> bool {
     return updated;
 }
 
+/// Initializes the blocking engine from the adblock-rust crate, returns the initialized engine.
+/// 
+/// If the engine configuration wasn't updated the engine data will be loaded from the serialized
+/// engine file, if it exists. If not, the files located in `lists_dir` will be processed as filter
+/// lists.
+///
+/// * `engine_file` - Path of the serialized engine file.
+/// * `lists_dir` - Directory path where the filter lists should be saved.
+/// * `updated` - Boolean which when set to true will cause the serialized engine file to be
+/// ingored.
 fn init_engine(engine_file: &str, lists_dir: &str, updated: bool) -> Engine {
     if Path::new(&engine_file).exists() && !updated {
         let mut blocker = Engine::new(true);
@@ -183,6 +212,12 @@ fn init_engine(engine_file: &str, lists_dir: &str, updated: bool) -> Engine {
     }
 }
 
+/// Starts handling incoming client connections. 
+/// 
+/// The socket file will get automatically removed if it already exists.
+///
+/// * `socket_path` - Path of the socket file used for communication.
+/// * `blocker` - The inialized Engine that should be used for filtering.
 fn start_server(socket_path: &str, blocker: Engine) {
     if std::path::Path::new(socket_path).exists() {
         fs::remove_file(socket_path).expect("Can't remove Unix domain socket file");
@@ -206,6 +241,12 @@ fn start_server(socket_path: &str, blocker: Engine) {
     }
 }
 
+/// Setup needed before initializing the server, returns the initialized Engine struct.
+/// 
+/// Consists of finding the $HOME directory, parsing the url file with `parse_urls` based on
+/// specified `init_type` and creating the custom filters file if it doesn't exist.
+///
+/// * `init_type` - Specifies the type of Engine initialization.
 fn setup_blocker(init_type: InitType) -> Engine {
     let home_dir = var("HOME").expect("Can't find environment variable $HOME");
     let config_dir = home_dir.to_owned() + "/.config/ars";
@@ -242,6 +283,8 @@ fn setup_blocker(init_type: InitType) -> Engine {
     return init_engine(&engine_file, &lists_dir, updated);
 }
 
+/// The main function that initializes the blocker with `setup_blocker` and starts the server with
+/// `start_server`.
 fn main() {
     let blocker = setup_blocker(InitType::Default);
     start_server("/tmp/ars", blocker);