From df3989a18731ec2416afdddea63c842057ee4f17 Mon Sep 17 00:00:00 2001
From: f <f@sutty.nl>
Date: Fri, 6 Oct 2023 17:38:40 -0300
Subject: [PATCH] docs: yard para MetadataTemplate

---
 app/models/metadata_template.rb | 60 +++++++++++++++++++++++++++++----
 1 file changed, 53 insertions(+), 7 deletions(-)

diff --git a/app/models/metadata_template.rb b/app/models/metadata_template.rb
index 3e133666..45e6a4d0 100644
--- a/app/models/metadata_template.rb
+++ b/app/models/metadata_template.rb
@@ -3,18 +3,22 @@
 # Representa la plantilla de un campo en los metadatos del artículo
 #
 # TODO: Validar el tipo de valor pasado a value= según el :type
-#
+# @todo ¿Es necesario pasar :type, :label, :help, :required si se pueden
+# obtener del layout a través de :name?
 MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
                               :value, :help, :required, :errors, :post,
                               :layout, keyword_init: true) do
   include Metadata::FrontMatterConcern
 
+  # @return [String]
   def inspect
     "#<#{self.class} site=#{site.name.inspect} post=#{post.id.inspect} value=#{value.inspect}>"
   end
 
   # Queremos que los artículos nuevos siempre cacheen, si usamos el UUID
   # siempre vamos a obtener un item nuevo.
+  #
+  # @return [String]
   def cache_key
     return "#{layout.value}/#{name}" if post.new?
 
@@ -25,6 +29,7 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
   # Post, el valor actual y los valores posibles, de forma que cualquier
   # cambio permita renovar la caché.
   #
+  # @todo no será demasiado traer #values acá
   # @return [String]
   def cache_version
     post.cache_version + value.hash.to_s + values.hash.to_s
@@ -35,7 +40,7 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
     "#{cache_key}-#{cache_version}"
   end
 
-  # XXX: Deberíamos sanitizar durante la asignación?
+  # @todo: Deberíamos sanitizar durante la asignación?
   def value=(new_value)
     @value_was = value
     self[:value] = new_value
@@ -43,17 +48,24 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
 
   # Siempre obtener el valor actual y solo obtenerlo del documento una
   # vez.
+  #
+  # @return [any]
   def value_was
     return @value_was if instance_variable_defined? '@value_was'
 
     @value_was = document_value
   end
 
+  # ¿Cambió?
+  #
+  # @return [Boolean]
   def changed?
     value_was != value
   end
 
   # Obtiene el valor del JekyllDocument
+  #
+  # @return [any]
   def document_value
     document.data[name.to_s]
   end
@@ -81,22 +93,33 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
   # usando otros métodos que el de asignación.
   def value
     self[:value] ||= if (data = document_value).present?
-                       private? ? decrypt(data) : data
+                       if private?
+                         decrypt(data)
+                       else
+                         data
+                       end
                      else
                        default_value
                      end
   end
 
   # Detecta si el valor está vacío
+  #
+  # @return [Boolean]
   def empty?
     value.blank?
   end
 
   # Comprueba si el metadato es válido
+  #
+  # @return [Boolean]
   def valid?
     validate
   end
 
+  # Ejecuta validaciones
+  #
+  # @return [Boolean]
   def validate
     self.errors = []
 
@@ -117,12 +140,17 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
     end
   end
 
+  # Convierte el valor a String
+  #
+  # @return [String]
   def to_s
     value.to_s
   end
 
   # En caso de que algún campo necesite realizar acciones antes de ser
   # guardado
+  #
+  # @return [Boolean]
   def save
     if !changed?
       self[:value] = document_value if private?
@@ -140,16 +168,23 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
     false
   end
 
+  # Métodos relacionados
+  #
+  # @return [Array]
   def related_methods
     @related_methods ||= [].freeze
   end
 
   # Determina si el campo es privado y debería ser cifrado
+  #
+  # @return [Boolean]
   def private?
     layout.metadata.dig(name, 'private').present?
   end
 
   # Determina si el campo debería estar deshabilitado
+  #
+  # @return [Boolean]
   def disabled?
     layout.metadata.dig(name, 'disabled') || !writable?
   end
@@ -157,6 +192,8 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
   # Determina si el campo es de solo lectura
   #
   # once => el campo solo se puede modificar si estaba vacío
+  #
+  # @return [Boolean]
   def writable?
     case layout.metadata.dig(name, 'writable')
     when 'once' then value.blank?
@@ -167,6 +204,8 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
   private
 
   # Si es obligatorio no puede estar vacío
+  #
+  # @return [Boolean]
   def can_be_empty?
     true unless required && empty?
   end
@@ -174,6 +213,9 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
   # No usamos sanitize_action_text_content porque espera un ActionText
   #
   # Ver ActionText::ContentHelper#sanitize_action_text_content
+  #
+  # @param :string [String]
+  # @return [String,nil]
   def sanitize(string)
     return if string.nil?
     return string unless string.is_a? String
@@ -186,6 +228,7 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
       .html_safe
   end
 
+  # @return [Rails::Html::Sanitizer]
   def sanitizer
     @sanitizer ||= Rails::Html::Sanitizer.safe_list_sanitizer.new
   end
@@ -202,8 +245,10 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
 
   # Decifra el valor
   #
-  # XXX: Otros tipos de valores necesitan implementar su propio método
-  # de decifrado (Array).
+  # @todo Agregar el error de decifrado en self.errors
+  # @todo Mover a su propio Concern
+  # @param :value [String]
+  # @return [String,nil]
   def decrypt(value)
     return value if value.blank?
 
@@ -220,8 +265,9 @@ MetadataTemplate = Struct.new(:site, :document, :name, :label, :type,
 
   # Cifra el valor.
   #
-  # XXX: Otros tipos de valores necesitan implementar su propio método
-  # de cifrado (Array).
+  # @todo serializar como JSON
+  # @param :value [String]
+  # @return [String]
   def encrypt(value)
     box.encrypt value.to_s
   end