From e9276e35ca14a195c05633364d83ac796ec9c1e1 Mon Sep 17 00:00:00 2001
From: Tom Alexander <tom@fizz.buzz>
Date: Sun, 8 Oct 2023 14:18:17 -0400
Subject: [PATCH] Add comments.

---
 src/types/object.rs | 36 +++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/src/types/object.rs b/src/types/object.rs
index 2397317..01435d4 100644
--- a/src/types/object.rs
+++ b/src/types/object.rs
@@ -84,9 +84,21 @@ pub struct PlainText<'s> {
 pub struct RegularLink<'s> {
     pub source: &'s str,
     pub link_type: LinkType<'s>,
+    /// The path after templates have been applied.
+    ///
+    /// This does not take into account the post-processing that you would get from the upstream emacs org-mode AST. Use `get_raw_link` for an equivalent value.
     pub path: Cow<'s, str>,
+
+    /// The raw link after templates have been applied.
+    ///
+    /// This does not take into account the post-processing that you would get from the upstream emacs org-mode AST. Use `get_raw_link` for an equivalent value.
     pub raw_link: Cow<'s, str>,
+
+    /// The search_option after templates have been applied.
+    ///
+    /// This does not take into account the post-processing that you would get from the upstream emacs org-mode AST. Use `get_search_option` for an equivalent value.
     pub search_option: Option<Cow<'s, str>>,
+
     pub children: Vec<Object<'s>>,
     pub application: Option<Cow<'s, str>>,
 }
@@ -119,8 +131,16 @@ pub struct PlainLink<'s> {
 pub struct AngleLink<'s> {
     pub source: &'s str,
     pub link_type: LinkType<'s>,
+
+    /// The path from the source.
+    ///
+    /// This does not take into account the post-processing that you would get from the upstream emacs org-mode AST. Use `get_raw_link` for an equivalent value.
     pub path: &'s str,
     pub raw_link: &'s str,
+
+    /// The search_option from the source.
+    ///
+    /// This does not take into account the post-processing that you would get from the upstream emacs org-mode AST. Use `get_search_option` for an equivalent value.
     pub search_option: Option<&'s str>,
     pub application: Option<&'s str>,
 }
@@ -667,17 +687,23 @@ pub enum LinkType<'s> {
 }
 
 impl<'s> RegularLink<'s> {
-    /// Orgify the raw_link if it contains line breaks.
+    /// Coalesce whitespace if the raw_link contains line breaks.
+    ///
+    /// This corresponds to the output you would get from the upstream emacs org-mode AST.
     pub fn get_raw_link<'b>(&'b self) -> Cow<'b, str> {
         coalesce_whitespace_if_line_break(&self.raw_link)
     }
 
-    /// Orgify the path if it contains line breaks.
+    /// Coalesce whitespace if the path contains line breaks.
+    ///
+    /// This corresponds to the output you would get from the upstream emacs org-mode AST.
     pub fn get_path<'b>(&'b self) -> Cow<'b, str> {
         coalesce_whitespace_if_line_break(&self.path)
     }
 
-    /// Orgify the search_option if it contains line breaks.
+    /// Coalesce whitespace if the search_option contains line breaks.
+    ///
+    /// This corresponds to the output you would get from the upstream emacs org-mode AST.
     pub fn get_search_option<'b>(&'b self) -> Option<Cow<'b, str>> {
         self.search_option
             .as_ref()
@@ -693,11 +719,15 @@ impl<'s> RadioLink<'s> {
 
 impl<'s> AngleLink<'s> {
     /// Remove line breaks but preserve multiple consecutive spaces.
+    ///
+    /// This corresponds to the output you would get from the upstream emacs org-mode AST.
     pub fn get_path(&self) -> Cow<'s, str> {
         remove_line_break(self.path)
     }
 
     /// Remove all whitespace but only if search_option contains a line break.
+    ///
+    /// This corresponds to the output you would get from the upstream emacs org-mode AST.
     pub fn get_search_option(&self) -> Option<Cow<'s, str>> {
         self.search_option.map(remove_whitespace_if_line_break)
     }