From 10841e980126316edc89e8202bc64b6d4e026a2c Mon Sep 17 00:00:00 2001
From: Monique Rio <mrio@umich.edu>
Date: Mon, 19 Aug 2024 14:52:43 -0400
Subject: [PATCH] docs: comments in subjects and remediated subjects

---
 lib/authority_browse/remediated_subjects.rb | 30 +++++++++++++++++++++
 lib/authority_browse/subjects.rb            | 11 ++++++++
 2 files changed, 41 insertions(+)

diff --git a/lib/authority_browse/remediated_subjects.rb b/lib/authority_browse/remediated_subjects.rb
index 77f15df0..f39352fb 100644
--- a/lib/authority_browse/remediated_subjects.rb
+++ b/lib/authority_browse/remediated_subjects.rb
@@ -2,6 +2,9 @@ module AuthorityBrowse
   class RemediatedSubjects
     include Enumerable
 
+    # List of RemediatedSubjects::Entriees
+    # @param file_path [String] Path to config file with remediated subjects
+    # info
     def initialize(file_path = S.remediated_subjects_file)
       xml_lines = File.readlines(file_path)
       @entries = xml_lines.map do |line|
@@ -14,6 +17,8 @@ def each(&block)
     end
 
     class Entry
+      # An Authority Record Entry
+      # @param xml [String] Authority Record MARCXML String
       def initialize(xml)
         @record = MARC::XMLReader.new(StringIO.new(xml)).first
       end
@@ -26,6 +31,8 @@ def preferred_term
         @preferred_term ||= Term::Preferred.new(@record["150"])
       end
 
+      # Returns the cross references found in the 450 and 550 fields
+      # @return [Array<Term>] An Array of xref terms
       def xrefs
         @record.fields(["450", "550"]).map do |field|
           [Term::SeeInstead, Term::Broader, Term::Narrower].find do |kind|
@@ -34,6 +41,9 @@ def xrefs
         end.compact
       end
 
+      # Adds the preferred term and xrefs to the subjects and subjects_xrefs
+      # db tables
+      # @return [Nil]
       def add_to_db
         preferred_term.add_to_db(id)
         xrefs.each do |xref|
@@ -43,20 +53,29 @@ def add_to_db
     end
 
     class Term
+      # @param field [MARC::DataField] A subject term field
       def initialize(field)
         @field = field
       end
 
+      # What kind of field it is. It's used for setting the xref_kind in the subjects_xrefs table.
       def kind
         raise NotImplementedError
       end
 
+      # This is the first step in adding the xref to term to the database. It's
+      # overwritten for a PreferredTerm. The check for id and match_text is to
+      # make sure the id isn't already in the db. If the id given is the match
+      # text that means the term isn't in the db.
+      #
+      # @param preferred_term_id [[TODO:type]] [TODO:description]
       def add_to_db(preferred_term_id)
         if id == match_text
           AuthorityBrowse.db[:subjects].insert(id: id, label: label, match_text: match_text, deprecated: false)
         end
       end
 
+      # @return [String]
       def label
         @field.subfields
           .filter_map do |x|
@@ -65,15 +84,20 @@ def label
           .join("--")
       end
 
+      # @return [String]
       def match_text
         AuthorityBrowse::Normalize.match_text(label)
       end
 
+      # @return [String]
       def id
         AuthorityBrowse.db[:subjects]&.first(match_text: match_text)&.dig(:id) || match_text
       end
 
       class Preferred < Term
+        # Adds the preferred term to the db
+        #
+        # @return nil
         def add_to_db(id)
           AuthorityBrowse.db[:subjects].insert(id: id, label: label, match_text: match_text, deprecated: false)
         end
@@ -88,6 +112,8 @@ def kind
           "see_instead"
         end
 
+        # @param preferred_term_id [String]
+        # @return [Nil]
         def add_to_db(preferred_term_id)
           super
           xrefs = AuthorityBrowse.db[:subjects_xrefs]
@@ -104,6 +130,8 @@ def kind
           "broader"
         end
 
+        # @param preferred_term_id [String]
+        # @return [Nil]
         def add_to_db(preferred_term_id)
           super
           xrefs = AuthorityBrowse.db[:subjects_xrefs]
@@ -121,6 +149,8 @@ def kind
           "narrower"
         end
 
+        # @param preferred_term_id [String]
+        # @return [Nil]
         def add_to_db(preferred_term_id)
           super
           xrefs = AuthorityBrowse.db[:subjects_xrefs]
diff --git a/lib/authority_browse/subjects.rb b/lib/authority_browse/subjects.rb
index a39162e9..4cabf1b9 100644
--- a/lib/authority_browse/subjects.rb
+++ b/lib/authority_browse/subjects.rb
@@ -8,6 +8,12 @@ def kind
         "subject"
       end
 
+      # Fetches and writes the MARCXML Authority record data for remediated
+      # subjects to a file.
+      #
+      # @param file_path [String] Path to remediated subjects config file
+      # @param set_id [String] Alma Set ID for remediated subjects authority records
+      # @return [Nil]
       def generate_remediated_authorities_file(file_path: S.remediated_subjects_file, set_id: S.subject_heading_remediation_set_id)
         conn = Faraday.new do |conn|
           conn.options.timeout = 10 * 60
@@ -76,6 +82,11 @@ def reset_db(loc_file_getter = lambda { fetch_skos_file })
         end
       end
 
+      # Adds the remediated subject information to the `subjects` and
+      # `subjects_xrefs` table of the database
+      #
+      # @param file_path [String] Path to remediated subjects config file
+      # @return [Nil]
       def incorporate_remediated_subjects(file_path = S.remediated_subjects_file)
         subjects = AuthorityBrowse::RemediatedSubjects.new(file_path)
         AuthorityBrowse.db.transaction do