Add soft delete documentation

src/avram/soft_delete/model.cr

@@ -1,14 +1,50 @@
+# Add methods for soft deleting and restoring an individual record
+#
+# Include this module in your model, and make sure to add a `soft_deleted_at`
+# column to your model. The column type must be `Time?`
+#
+# ```crystal
+# # In a migration
+# add soft_deleted_at : Time?
+#
+# # In your model
+# class Article < BaseModel
+#   include Avram::SoftDelete::Model
+
+#   table do
+#     column soft_deleted_at : Time?
+#   end
+# end
+# ```
+#
+# You should also add the `Avram::SoftDeleteQuery` to your query
+#
+# ```crystal
+# class ArticleQuery < Article::BaseQuery
+#   include Avram::SoftDelete::Query
+# end
+# ```
 module Avram::SoftDelete::Model
+  # Soft delete the record
+  #
+  # This will set `soft_deleted_at` to the current time (`Time.utc`)
   def soft_delete : self
     save_operation_class.update!(self, soft_deleted_at: Time.utc)
   end
 
+  # Restore the record
+  #
+  # This will set `soft_deleted_at` to `nil`
   def restore : self
     save_operation_class.update!(self, soft_deleted_at: nil)
   end
 
   abstract def save_operation_class
 
+  # Returns true if soft deleted, otherwise false
+  #
+  # If the `soft_deleted_at` has a time value the record is "soft deleted".
+  # If `soft_deleted_at` is `nil` the record has not been deleted yet.
   def soft_deleted? : Bool
     soft_deleted_at.present?
   end

src/avram/soft_delete/query.cr

@@ -1,20 +1,62 @@
+# Add methods for querying/updating soft deleted and kept records.
+#
+# First include the model module in your model: `Avram::SoftDelete::Model`
+#
+# Then add this module your query
+#
+# ```crystal
+# class ArticleQuery < Article::BaseQuery
+#   include Avram::SoftDelete::Query
+# end
+# ```
 module Avram::SoftDelete::Query
+  # Only return kept records
+  #
+  # Kept records are considered "kept/not soft deleted" if the
+  # `soft_deleted_at` column is `nil`
   def only_kept
     soft_deleted_at.is_nil
   end
 
+  # Only return soft deleted records
+  #
+  # Soft deleted records are considered "soft deleted" if the
+  # `soft_deleted_at` column has a non-nil value
   def only_soft_deleted
     soft_deleted_at.is_not_nil
   end
 
+  # Returns all records
+  #
+  # This works be removing where clauses for the `soft_deleted_at` column.
+  # That means you can do `MyQuery.new.only_kept.with_soft_deleted` and you
+  # will get all records, not just the kept ones.
   def with_soft_deleted
     reset_where(&.soft_deleted_at)
   end
 
+  # Bulk soft delete records
+  #
+  # ## Example
+  #
+  # This will soft delete all `Article` record older than 1 year:
+  #
+  # ```crystal
+  # ArticleQuery.new.created_at.lt(1.year.ago).soft_delete
+  # ```
   def soft_delete
     only_kept.update(soft_deleted_at: Time.utc)
   end
 
+  # Bulk restore records
+  #
+  # ## Example
+  #
+  # This will restore `Article` records updated in the last week:
+  #
+  # ```crystal
+  # ArticleQuery.new.updated_at.gt(1.week.ago).restore
+  # ```
   def restore : Int64
     only_soft_deleted.update(soft_deleted_at: nil)
   end