Merge pull request #379 from samvera-labs/header_perister

Adding header level comments for Persister tree

lib/valkyrie/persistence.rb

@@ -1,5 +1,29 @@
 # frozen_string_literal: true
 module Valkyrie
+  # This is a namespacing module for metadata persisters as per the DataMapper pattern
+  #  https://en.wikipedia.org/wiki/Data_mapper_pattern
+  #
+  # @note These persisters do not store binary content.
+  #       See Valkyrie::Storage for persisting binary content (files).
+  #
+  # @example Register persisters in an initializer using Valkyrie::MetadataAdapter.register
+  #   Valkyrie::MetadataAdapter.register(
+  #     Valkyrie::Persistence::Memory::MetadataAdapter.new,
+  #     :memory
+  #   )
+  #
+  # @example Retrieve a registered persister using Valkyrie::MetadataAdapter.find
+  #   Valkyrie::MetadataAdapter.find(:memory)
+  #   => <Valkyrie::Persistence::Memory::MetadataAdapter:0x007fa6ec031bd8>
+  #
+  # @example Saving an object
+  #
+  #   object1 = MyModel.new title: 'My Cool Object', authors: ['Jones, Alice', 'Smith, Bob']
+  #   object1 = Valkyrie.config.metadata_adapter.persister.save(model: object1)
+  #
+  # @see https://github.com/samvera-labs/valkyrie/wiki/Persistence
+  # @see lib/valkyrie/specs/shared_specs/persister.rb
+  #
   module Persistence
     require 'valkyrie/persistence/custom_query_container'
     require 'valkyrie/persistence/memory'

lib/valkyrie/persistence/buffered_persister.rb

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to proxy another Metadata Persister
+  #
+  # Provides with_buffer to send multiple updates at one time to the proxied persister
+  #  In some cases this will realize performance gains
+  #
+  # @example
+  #     buffered_persister.with_buffer do |persist, buffer|
+  #       yield Valkyrie::AdapterContainer.new(persister: persist, query_service: metadata_adapter.query_service)
+  #       buffer.persister.deletes.uniq(&:id).each do |delete|
+  #         index_persister.delete(resource: delete)
+  #       end
+  #       index_persister.save_all(resources: buffer.query_service.find_all)
+  #     end
+  #
+  # @see Valkyrie::Persistence::DeleteTrackingBuffer for more information on deletes used in the example above
+  #
   class BufferedPersister
     attr_reader :persister, :buffer_class
     delegate :adapter, :wipe!, to: :persister

lib/valkyrie/persistence/composite_persister.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
-  ##
-  # Wrap up multiple persisters under a common interface, to transparently
+  # Wraps up multiple persisters under a common interface, to transparently
   # persist to multiple places at once.
+  #
+  # @example
+  #   persister = Valkyrie.config.metadata_adapter
+  #   index_persister = Valkyrie::MetadataAdapter.find(:index_solr)
+  #   Valkyrie::MetadataAdapter.register(
+  #     Valkyrie::Persistence::CompositePersister.new(persister, index_persister),
+  #     :my_composite_persister
+  #   )
+  #
   class CompositePersister
     attr_reader :persisters
     def initialize(*persisters)

lib/valkyrie/persistence/custom_query_container.rb

@@ -1,5 +1,40 @@
 # frozen_string_literal: true
+
 module Valkyrie::Persistence
+  # Allows for implementors to register and use custom queries on a
+  #  per persister basis
+  #
+  # @example Custom Query Class
+  #
+  #     # Snippet from custom query class see: https://github.com/pulibrary/figgy/blob/d0b1305a1564c2aa4e7d6c1e99f0c2a88ed673f4/app/queries/find_by_string_property.rb
+  #     class FindByStringProperty
+  #       def self.queries
+  #         [:find_by_string_property]
+  #       end
+  #
+  #       ...
+  #
+  #       def initialize(query_service:)
+  #         @query_service = query_service
+  #       end
+  #       ...
+  #
+  #       def find_by_string_property(property:, value:)
+  #         internal_array = "{\"#{property}\": [\"#{value}\"]}"
+  #         run_query(query, internal_array)
+  #       end
+  #       ...
+  #     end
+  #
+  # @example Registration
+  #
+  #   # in config/initializers/valkyrie.rb
+  #   [FindByStringProperty].each do |query_handler|
+  #     Valkyrie.config.metadata_adapter.query_service.custom_queries.register_query_handler(query_handler)
+  #   end
+  #
+  # @see lib/valkyrie/persistence/solr/query_service.rb for use of this class
+  #
   class CustomQueryContainer
     attr_reader :query_service, :query_handlers
     def initialize(query_service:)

lib/valkyrie/persistence/delete_tracking_buffer.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata in Memory
+  #  In Addition this stores an array of all deleted resources
+  #
+  # This is used by the Valkyrie::Persistence::BufferedPersister to
+  #   buffer deletes for efficiency
+  #
+  # @see Valkyrie::Persistence::BufferedPersister
+  #
   class DeleteTrackingBuffer < Valkyrie::Persistence::Memory::MetadataAdapter
     def persister
       @persister ||= DeleteTrackingBuffer::Persister.new(self)

lib/valkyrie/persistence/fedora.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata into Fedora
   module Fedora
     require 'valkyrie/persistence/fedora/permissive_schema'
     require 'valkyrie/persistence/fedora/metadata_adapter'

lib/valkyrie/persistence/memory.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata in memory
   module Memory
     require 'valkyrie/persistence/memory/metadata_adapter'
     require 'valkyrie/persistence/memory/persister'

lib/valkyrie/persistence/postgres.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+#
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata into Postgres
   module Postgres
     require 'valkyrie/persistence/postgres/metadata_adapter'
   end

lib/valkyrie/persistence/solr.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 module Valkyrie::Persistence
+  # Implements the DataMapper Pattern to store metadata into Solr
   module Solr
     require 'valkyrie/persistence/solr/metadata_adapter'
     require 'valkyrie/persistence/solr/composite_indexer'