From 464bd6dfdb9a1dfb6389433060113baed39fdd90 Mon Sep 17 00:00:00 2001
From: Alexandre Pasmantier <alex.pasmant@gmail.com>
Date: Tue, 29 Apr 2025 18:28:59 +0200
Subject: [PATCH] refactor(cable): improve naming and documentation for
 `prototypes.rs`

---
 television/cable.rs                     |  6 ++--
 television/channels/cable/prototypes.rs | 45 +++++++++++++++++++++----
 2 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/television/cable.rs b/television/cable.rs
index d4fda31..7c16c2e 100644
--- a/television/cable.rs
+++ b/television/cable.rs
@@ -12,7 +12,7 @@ use crate::{
 
 /// Just a proxy struct to deserialize prototypes
 #[derive(Debug, serde::Deserialize, Default)]
-pub struct ChannelPrototypes {
+pub struct SerializedChannelPrototypes {
     #[serde(rename = "cable_channel")]
     pub prototypes: Vec<CableChannelPrototype>,
 }
@@ -58,13 +58,13 @@ pub fn load_cable_channels() -> Result<CableChannels> {
     }
 
     let default_prototypes =
-        toml::from_str::<ChannelPrototypes>(DEFAULT_CABLE_CHANNELS)
+        toml::from_str::<SerializedChannelPrototypes>(DEFAULT_CABLE_CHANNELS)
             .expect("Failed to parse default cable channels");
 
     let prototypes = file_paths.iter().fold(
         Vec::<CableChannelPrototype>::new(),
         |mut acc, p| {
-            match toml::from_str::<ChannelPrototypes>(
+            match toml::from_str::<SerializedChannelPrototypes>(
                 &std::fs::read_to_string(p)
                     .expect("Unable to read configuration file"),
             ) {
diff --git a/television/channels/cable/prototypes.rs b/television/channels/cable/prototypes.rs
index b36051b..05e04a3 100644
--- a/television/channels/cable/prototypes.rs
+++ b/television/channels/cable/prototypes.rs
@@ -4,8 +4,36 @@ use std::{
     ops::Deref,
 };
 
-use crate::cable::ChannelPrototypes;
+use crate::cable::SerializedChannelPrototypes;
 
+/// A prototype for a cable channel.
+///
+/// This can be seen as a cable channel specification, which is used to
+/// create a cable channel.
+///
+/// The prototype contains the following fields:
+/// - `name`: The name of the channel. This will be used to identify the
+///     channel throughout the application and in UI menus.
+/// - `source_command`: The command to run to get the source for the channel.
+///     This is a shell command that will be run in the background.
+/// - `interactive`: Whether the source command should be run in an interactive
+///     shell. This is useful for commands that need the user's environment e.g.
+///     `alias`.
+/// - `preview_command`: The command to run on each entry to get the preview
+///     for the channel. If this is not `None`, the channel will display a preview
+///     pane with the output of this command.
+/// - `preview_delimiter`: The delimiter to use to split an entry into
+///     multiple parts that can then be referenced in the preview command (e.g.
+///     `{1} + {2}`).
+///
+/// # Example
+/// The default files channel might look something like this:
+/// ```toml
+/// [[cable_channel]]
+/// name = "files"
+/// source_command = "fd -t f"
+/// preview_command = ":files:"
+/// ```
 #[derive(Clone, Debug, serde::Deserialize, PartialEq)]
 pub struct CableChannelPrototype {
     pub name: String,
@@ -38,6 +66,7 @@ impl CableChannelPrototype {
 const DEFAULT_PROTOTYPE_NAME: &str = "files";
 const DEFAULT_SOURCE_COMMAND: &str = "fd -t f";
 const DEFAULT_PREVIEW_COMMAND: &str = ":files:";
+pub const DEFAULT_DELIMITER: &str = " ";
 
 impl Default for CableChannelPrototype {
     fn default() -> Self {
@@ -51,8 +80,6 @@ impl Default for CableChannelPrototype {
     }
 }
 
-pub const DEFAULT_DELIMITER: &str = " ";
-
 #[allow(clippy::unnecessary_wraps)]
 fn default_delimiter() -> Option<String> {
     Some(DEFAULT_DELIMITER.to_string())
@@ -64,6 +91,11 @@ impl Display for CableChannelPrototype {
     }
 }
 
+/// A neat `HashMap` of cable channel prototypes indexed by their name.
+///
+/// This is used to store cable channel prototypes throughout the application
+/// in a way that facilitates answering questions like "what's the prototype
+/// for `files`?" or "does this channel exist?".
 #[derive(Debug, serde::Deserialize)]
 pub struct CableChannels(pub FxHashMap<String, CableChannelPrototype>);
 
@@ -86,9 +118,10 @@ impl Default for CableChannels {
     /// Fallback to the default cable channels specification (the template file
     /// included in the repo).
     fn default() -> Self {
-        let pts =
-            toml::from_str::<ChannelPrototypes>(DEFAULT_CABLE_CHANNELS_FILE)
-                .expect("Unable to parse default cable channels");
+        let pts = toml::from_str::<SerializedChannelPrototypes>(
+            DEFAULT_CABLE_CHANNELS_FILE,
+        )
+        .expect("Unable to parse default cable channels");
         let mut channels = FxHashMap::default();
         for prototype in pts.prototypes {
             channels.insert(prototype.name.clone(), prototype);