Add crate documentation

Cargo.toml

@@ -2,6 +2,12 @@
 name = "countryinfo-rs"
 version = "0.1.0"
 edition = "2021"
+authors = ["Malhar Vora <[email protected]>"]
+description = "A crate to get information about countries."
+readme = "README.md"
+repository = "https://github.com/vbmade2000/countryinfo-rs"
+license = "MIT"
+keywords = ["country", "information"]
 
 [dependencies]
 serde_json = "1.0"

README.md

@@ -1,2 +1,11 @@
 # countryinfo-rs
-Rust port for countryinfo Python package
+Rust crate to get country information, inspired from [countryinfo](https://pypi.org/project/countryinfo/).
+
+### Built crate
+```cargo build --release```
+
+### Run unit tests
+```cargo test```
+
+### Build documentation
+```cargo doc --no-deps --open```

src/country.rs

@@ -1,7 +1,9 @@
+//! Contains the `Country` struct which is used to represent a country.
 use crate::geo_json::GeoJSON;
 use serde_derive::Deserialize;
 use std::collections::HashMap;
 
+/// A struct representing a country.
 #[derive(Clone, Deserialize, Debug)]
 pub struct Country {
     pub name: String,

src/countryinfo.rs

@@ -1,3 +1,4 @@
+//! Contains the CountryInfo struct which is used to get information about a country.
 use crate::{country::Country, geo_json::GeoJSON};
 use std::{
     collections::HashMap,
@@ -6,14 +7,17 @@ use std::{
     path::PathBuf,
 };
 
+// Path to the data directory
 const PATH: &str = "./data/";
 const FILE_EXTENSION: &str = "json";
 
+/// A struct to get country information.
 pub struct CountryInfo {
     pub country: String,
     pub countries: HashMap<String, Country>,
 }
 
+// Reads a file and returns the Country struct
 fn read_country_data_from_file(path: &PathBuf) -> Result<Country, Error> {
     let file = File::open(&path)?; // .expect(format!("Error in opening {}", &filename).as_str());
     let buf_reader = BufReader::new(file);
@@ -53,175 +57,175 @@ impl CountryInfo {
 }
 
 impl CountryInfo {
-    // Get the list of countries for the country specified in the constructor
+    /// Get the list of countries for the country specified in the constructor
     pub fn get_provinces(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.provinces.clone();
         }
         return None;
     }
 
-    // Get the list of alternative spellings for the country specified in the constructor
+    /// Get the list of alternative spellings for the country specified in the constructor
     pub fn get_alt_spellings(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.alt_spellings.clone();
         }
         return None;
     }
 
-    // Get the wikipedia link for the country specified in the constructor
+    /// Get the wikipedia link for the country specified in the constructor
     pub fn get_wiki(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.wiki.clone();
         }
         return None;
     }
 
-    // Get the list of translations for the country specified in the constructor
+    /// Get the list of translations for the country specified in the constructor
     pub fn get_translations(&self) -> Option<HashMap<String, String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.translations.clone();
         }
         return None;
     }
 
-    // Get the top level domains for the country specified in the constructor
+    /// Get the top level domains for the country specified in the constructor
     pub fn get_tlds(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.tlds.clone();
         }
         return None;
     }
 
-    // Get timezones for the country specified in the constructor
+    /// Get timezones for the country specified in the constructor
     pub fn get_timezones(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.timezones.clone();
         }
         return None;
     }
 
-    // Get subregion for the country specified in the constructor
+    /// Get subregion for the country specified in the constructor
     pub fn get_subregion(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.subregion.clone();
         }
         return None;
     }
 
-    // Get region for the country specified in the constructor
+    /// Get region for the country specified in the constructor
     pub fn get_region(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.region.clone();
         }
         return None;
     }
 
-    // Get population of the country specified in the constructor
+    /// Get population of the country specified in the constructor
     pub fn get_population(&self) -> Option<u64> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.population;
         }
         return None;
     }
 
-    // Get native name of the country specified in the constructor
+    /// Get native name of the country specified in the constructor
     pub fn get_native_name(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.native_name.clone();
         }
         return None;
     }
 
-    // Get lat long of the country specified in the constructor
+    /// Get lat long of the country specified in the constructor
     pub fn get_lat_long(&self) -> Option<Vec<f64>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.lat_lng.clone();
         }
         return None;
     }
 
-    // Get languages of the country specified in the constructor
+    /// Get languages of the country specified in the constructor
     pub fn get_languages(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.languages.clone();
         }
         return None;
     }
 
-    // Get geo-json of the country specified in the constructor
+    /// Get geo-json of the country specified in the constructor
     pub fn get_geo_json(&self) -> Option<GeoJSON> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.geo_json.clone();
         }
         return None;
     }
 
-    // Get SVG link of flag of the country specified in the constructor
+    /// Get SVG link of flag of the country specified in the constructor
     pub fn get_flag(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.flag.clone();
         }
         return None;
     }
 
-    // Get demonym of the country specified in the constructor
+    /// Get demonym of the country specified in the constructor
     pub fn get_demonym(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.demonym.clone();
         }
         return None;
     }
 
-    // Get currencies of the country specified in the constructor
+    /// Get currencies of the country specified in the constructor
     pub fn get_currencies(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.currencies.clone();
         }
         return None;
     }
 
-    // Get latitude and longitude of the capital of the country specified in the constructor
+    /// Get latitude and longitude of the capital of the country specified in the constructor
     pub fn get_capital_lat_long(&self) -> Option<Vec<f64>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.capital_latlng.clone();
         }
         return None;
     }
 
-    // Get capital of the country specified in the constructor
+    /// Get capital of the country specified in the constructor
     pub fn get_capital(&self) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.capital.clone();
         }
         return None;
     }
 
-    // Get calling codes of the country specified in the constructor
+    /// Get calling codes of the country specified in the constructor
     pub fn get_calling_codes(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.calling_codes.clone();
         }
         return None;
     }
 
-    // Get borders of the country specified in the constructor
+    /// Get borders of the country specified in the constructor
     pub fn get_borders(&self) -> Option<Vec<String>> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.borders.clone();
         }
         return None;
     }
 
-    // Get area of the country specified in the constructor
+    /// Get area of the country specified in the constructor
     pub fn get_area(&self) -> Option<u64> {
         if let Some(country) = self.countries.get(&self.country) {
             return country.area.clone();
         }
         return None;
     }
 
-    // Get ISO codes of the country specified in the constructor
+    /// Get ISO codes of the country specified in the constructor
     pub fn get_iso_codes(&self, alpha: String) -> Option<String> {
         if let Some(country) = self.countries.get(&self.country) {
             let iso_codes = country.iso.clone().unwrap();
@@ -234,12 +238,11 @@ impl CountryInfo {
         return None;
     }
 
-    // Get all the info of the country specified in the constructor
+    /// Get all the info of the country specified in the constructor
     pub fn get_all_info(&self) -> Option<Country> {
         if let Some(country) = self.countries.get(&self.country) {
             return Some(country.clone());
         }
         return None;
     }
-
 }

src/lib.rs

@@ -1,3 +1,25 @@
+//! A crate to get country information like country name, capital, area, population, etc. Inspired from https://pypi.org/project/countryinfo/.
+//!
+//! # Usage
+//! Use a [`countryinfo::CountryInfo`] struct to get information about a country.
+//! ## Instantiate the struct
+//! ```rust,ignore
+//! use countryinfo_rs::CountryInfo;
+//! let country_info = CountryInfo::new("India".to_string());
+//! ```
+//! ## Get the information
+//! ```rust,ignore
+//! let capital = country_info.get_capital().unwrap();
+//! println!("Capital: {}", capital);   // Capital: New Delhi
+//! ```
+//! ## Get all the information
+//! ```rust,ignore
+//! let country = country_info.get_all_info().unwrap();
+//! println!("{:?}", country);
+//! ```
+//! In the same way as shown above, you can get other information like area, population, etc.
+//! Checkout [Examples](https://github.com/vbmade2000/countryinfo-rs/tree/main/examples).
+
 pub mod country;
 pub mod countryinfo;
 pub mod geo_json;