Documentation up the wazoo

Author: BrenekH

src/lib.rs

@@ -1,31 +1,40 @@
+//! Create markdown tables for [Locatarr](https://github.com/Locatarr/Locatarr)
+
 use itertools::Itertools;
 
 use models::{Application, Applications};
 
 pub mod models;
 
+/// Generate a fully valid markdown table from an [Applications] struct.
+///
+/// The resulting table is the minimum viable table and is not formatted in any way.
 pub fn generate_md_table(apps: &Applications) -> String {
- "| **Service** | **Usage** | **Github** | **Reddit** |\n|-------------|-----------|------------|------------|\n".to_owned() +
+ "| **Application** | **Description** | **Github** | **Reddit** |\n|-|-|-|-|\n".to_owned() +
  &apps.applications
  .iter()
  .sorted()
  .map(generate_md_row)
  .join("\n")
 }
 
+/// Create one markdown table row from a single [Application]
+///
+/// Copies the [Application::name] and [Application::description] fields in, and transforms [Application::github_slug] and
+/// [Application::subreddit] into proper markdown links.
 fn generate_md_row(app: &Application) -> String {
  let github_link = match &app.github_slug {
  Some(slug) => format!("[{}](https://github.com/{})", slug, slug),
  None => String::new(),
  };
 
  let subreddit_link = match &app.subreddit {
- Some(sub) => format!("[{}](http://reddit.com/{})", sub, sub),
+ Some(sub) => format!("[{}](https://reddit.com/{})", sub, sub),
  None => String::new(),
  };
 
  // Output in table format of:
- // | Service | Usage | GitHub | Reddit |
+ // | Application | Description | GitHub | Reddit |
  format!(
  "| {} | {} | {} | {} |",
  app.name, app.description, github_link, subreddit_link

src/main.rs

@@ -3,6 +3,7 @@ use std::path::PathBuf;
 
 use locatarr_json_to_readme::{generate_md_table, models::Applications};
 
+/// Cli derives a clap parser to allow us to handle command line arguments
 #[derive(Parser)]
 #[command(version, about, long_about = None)]
 struct Cli {
@@ -11,17 +12,24 @@ struct Cli {
  json_file_path: Option<PathBuf>,
 }
 
+/// You Already Know What It Is!
+/// The entry point function.
 fn main() {
  let cli = Cli::parse();
 
+ // The following match checks for whether to create an input stream from a user provided
+ // file path or from the standard input stream.
  let input_stream: Box<dyn std::io::Read + 'static> = match (
  cli.json_file_path.clone(),
  cli.json_file_path
  .unwrap_or("".into())
  .to_str()
  .unwrap_or(""),
  ) {
+ // Use stdin if we weren't provided a file path, or the file path was '-'
  (Some(_), "-") | (None, _) => Box::new(std::io::stdin()),
+
+ // Otherwise, use the provided file path
  (Some(file_path), _) => {
  if let Ok(file) = std::fs::File::open(file_path) {
  Box::new(file)

src/models.rs

@@ -1,19 +1,29 @@
+//! The models sub-crate holds all of the general purpose structs used throughout the library.
+
 use serde::{Deserialize, Serialize};
 
+/// Struct for the collection of a list of applications so that [serde] can deserialize a JSON
+/// file.
 #[derive(Serialize, Deserialize, Debug, Clone)]
 pub struct Applications {
  pub applications: Vec<Application>,
 }
 
+/// Holding struct for each application to place in a table
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct Application {
+ /// The name of the application/service
  pub name: String,
+ /// The description of the application/service
  pub description: String,
+ /// Optional GitHub slug (`<owner>/<repo name>`) for the application/service
  pub github_slug: Option<String>,
+ /// Optional subreddit slug (`r/<subreddit>`) for the application/service
  pub subreddit: Option<String>,
 }
 
 impl Application {
+ /// Create a new [Application] from various string references instead of owned strings
  #[allow(dead_code)] // Because I like this function here, but we aren't currently using it anywhere
  pub fn new_from_strs(
  name: &str,