From ed6065a19d9190cc02a66612906261bb1d4c2104 Mon Sep 17 00:00:00 2001
From: Raamakrishnan <raamakrishnan1997@gmail.com>
Date: Sun, 2 Feb 2020 13:42:24 +0530
Subject: [PATCH] Update Readme and cargo docs

---
 README.md          | 24 ++++++++++++++++++++++--
 src/file_parser.rs | 18 ++++++++++++++++++
 src/lib.rs         | 28 ++++++++++++++++++++++++++--
 3 files changed, 66 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 46d253d..0981504 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,23 @@
-# verilog-filelist-parser
+# Verilog Filelist Parser
 
-A Verilog Filelist parser in Rust
\ No newline at end of file
+A library in Rust to parse a Verilog Filelist and return
+a list of files, include directories and defines
+
+# Example
+```rust
+use verilog_filelist_parser;
+let filelist = verilog_filelist_parser::parse_file("testcase/files.f")
+    .expect("Cannot read filelist");
+for file in filelist.files {
+    println!("{:?}", file);
+}
+for incdir in filelist.incdirs {
+    println!("{:?}", incdir);
+}
+for (d, t) in filelist.defines {
+    match t {
+        None => println!("{:?}", d),
+        Some(te) => println!("{:?}={:?}", d, te),
+    };
+}
+```
diff --git a/src/file_parser.rs b/src/file_parser.rs
index 2c758bd..0b65cb6 100644
--- a/src/file_parser.rs
+++ b/src/file_parser.rs
@@ -7,16 +7,23 @@ use std::path::PathBuf;
 use crate::line_parser;
 use crate::line_parser::LineType;
 
+/// Represents a Verilog Filelist
 #[derive(PartialEq, Debug, Default)]
 pub struct Filelist {
+    /// List of all files
     pub files: Vec<PathBuf>,
+    /// List of all Include Directories
     pub incdirs: Vec<PathBuf>,
+    /// HashMap of all Defines
     pub defines: HashMap<String, Option<String>>,
+    /// True if comments are present in the filelist
     pub comments_present: bool,
+    /// True if unknown arguments are present in the filelist
     pub unknowns_present: bool,
 }
 
 impl Filelist {
+    /// Returns an empty Filelist
     pub fn new() -> Filelist {
         Filelist {
             files: Vec::new(),
@@ -27,6 +34,7 @@ impl Filelist {
         }
     }
 
+    /// Adds the elements of the other filelist to the current filelist
     pub fn extend(&mut self, other: Filelist) {
         self.files.extend(other.files);
         self.incdirs.extend(other.incdirs);
@@ -36,6 +44,16 @@ impl Filelist {
     }
 }
 
+/// Parses a filelist file
+///
+/// # Arguments
+///
+/// * `path` - A string slice that is the path to the filelist file
+///
+/// # Errors
+///
+/// Returns an error if the filelist in `path` cannot be read. Also returns
+/// error if any of the nested filelists cannot be read.
 pub fn parse_file(path: &str) -> Result<Filelist, Box<dyn Error>> {
     let contents = fs::read_to_string(path)?;
 
diff --git a/src/lib.rs b/src/lib.rs
index 6e06f64..a9b5877 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,29 @@
-pub mod file_parser;
-pub mod line_parser;
+//! # Verilog Filelist Parser
+//! 
+//! A library to parse a Verilog Filelist and return
+//! a list of files, include directories and defines
+//! 
+//! # Example
+//! ```
+//! use verilog_filelist_parser;
+//! let filelist = verilog_filelist_parser::parse_file("testcase/files.f")
+//!     .expect("Cannot read filelist");
+//! for file in filelist.files {
+//!     println!("{:?}", file);
+//! }
+//! for incdir in filelist.incdirs {
+//!     println!("{:?}", incdir);
+//! }
+//! for (d, t) in filelist.defines {
+//!     match t {
+//!         None => println!("{:?}", d),
+//!         Some(te) => println!("{:?}={:?}", d, te),
+//!     };
+//! }
+//! ```
+
+mod file_parser;
+mod line_parser;
 
 pub use file_parser::parse_file;
 pub use file_parser::Filelist;