docs + version bump

CHANGELOG.md

@@ -4,6 +4,8 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
+
+# [0.3.1] 2016-12-28
 * Mysql Adapter
 * moved association `preload` to `Query` instead of `Repo.all` option
 * joins queries and `has_many through` associations
@@ -32,5 +34,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 * Query
 * Postgres Adapter
 
+[0.3.1]: https://github.com/fridgerator/crecto/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/fridgerator/crecto/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/fridgerator/crecto/compare/0.1.0...v0.2.0

README.md

@@ -6,6 +6,8 @@ Database wrapper for Crystal.  Inspired by [Ecto](https://github.com/elixir-ecto
 
 [![Build Status](https://travis-ci.org/fridgerator/crecto.svg?branch=master)](https://travis-ci.org/fridgerator/crecto) [![Join the chat at https://gitter.im/crecto/Lobby](https://badges.gitter.im/crecto/Lobby.svg)](https://gitter.im/crecto/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
+#### [Docs](http://docs.crecto.com)
+
 ## Installation
 
 Add this to your application's `shard.yml`:
@@ -34,12 +36,12 @@ Make sure you have `ENV["MYSQL_URL"]` set
 
 #### Roadmap (in no particular order)
 
-- [ ] specify `select` in query
 - [x] MySQL adapter
 - [ ] SQLite adapter
 - [x] Associations
 - [x] Preload
 - [x] Joins
+- [ ] Association / dependent options (`dependent: :delete_all`, `dependent: :nilify_all`, etc)
 
 ## Usage
 

src/crecto.cr

@@ -4,8 +4,11 @@ require "./crecto/adapters/*"
 require "./crecto/changeset/*"
 require "./crecto/*"
 
+# :nodoc:
 alias DbBigInt = Int32 | Int64
+# :nodoc:
 alias DbValue = Bool | Float32 | Float64 | Int64 | Int32 | String | Time | Nil
+# :nodoc:
 alias PkeyValue = Int32 | Int64 | Nil
 
 module Crecto

src/crecto/db.cr

@@ -1,6 +1,8 @@
 #
 # 	Override crystal-pg `self.drivers` be public so we can see which driver is being used
 #
+
+# :nodoc:
 module DB
   def self.drivers
     @@drivers ||= {} of String => Driver.class

src/crecto/errors/crecto_error.cr

@@ -1,4 +1,5 @@
 module Crecto
+  # :nodoc:
   class CrectoError < Exception
   end
 end

src/crecto/errors/invalid_adapter.cr

@@ -0,0 +1,5 @@
+module Crecto
+  # :nodoc:
+  class InvalidAdapter < CrectoError
+  end
+end

src/crecto/errors/invalid_option.cr

@@ -1,4 +1,5 @@
 module Crecto
+  # :nodoc:
   class InvalidOption < CrectoError
   end
 end

src/crecto/errors/invalid_type.cr

@@ -1,4 +1,5 @@
 module Crecto
+  # :nodoc:
   class InvalidType < CrectoError
   end
 end

src/crecto/model.cr

@@ -1,4 +1,16 @@
 module Crecto
+
+  #Your data models should extend `Crecto::Model`:
+  #
+  # `class User < Crecto::Model`
+  #  -or-
+  #
+  # ```
+  # class User
+  #   include Crecto::Schema
+  #   extend Crecto::Changeset(User)
+  # end
+  # ```
   abstract class Model
     macro inherited
       include Crecto::Schema

src/crecto/query.cr

@@ -1,10 +1,11 @@
 module Crecto
   module Repo
+    # :nodoc:
     alias WhereType = Hash(Symbol, PkeyValue) | Hash(Symbol, DbValue) | Hash(Symbol, Array(DbValue)) | Hash(Symbol, Array(PkeyValue)) | Hash(Symbol, Array(Int32)) | Hash(Symbol, Array(Int64)) | Hash(Symbol, Array(String)) | Hash(Symbol, Int32 | String) | Hash(Symbol, Int32) | Hash(Symbol, Int64) | Hash(Symbol, String) | Hash(Symbol, Int32 | Int64 | String | Nil) | NamedTuple(clause: String, params: Array(DbValue | PkeyValue))
 
     # Queries are used to retrieve and manipulate data from a repository.  Syntax is much like that of ActiveRecord:
     #
-    # `Query.select('id').where(name: "fred").join(Post, where: {name: "this post"}).order_by("users.name").limit(1).offset(4)`
+    # `Query.select('id').where(name: "fred").join(:posts).order_by("users.name").limit(1).offset(4)`
     #
     class Query
       property selects : Array(String)
@@ -17,65 +18,118 @@ module Crecto
       property offset : Int32?
 
       # Fields to select, separated by comma.  Default is "*"
-      def self.select(selects)
-        self.new.select("*")
+      #
+      # ```
+      # Query.select(['id', 'name'])
+      # ```
+      def self.select(selects : Array(String))
+        self.new.select(selects)
       end
 
       # Key => Value pair(s) used in query `WHERE`
+      #
+      # ```
+      # Query.where(name: "Thor", age: 60)
+      # ```
       def self.where(**wheres)
         self.new.where(**wheres)
       end
 
-      # Query where with a string (i.e. `.where("users.id > 10"))
+      # Query WHERe with a string
+      #
+      # ```
+      # Query.where("users.id > ?", [10])
+      # ```
       def self.where(where_string : String, params : Array(DbValue | PkeyValue))
         self.new.where(where_string, params)
       end
 
-      # Query where with a Symbol and DbValue
+      # Query WHERe with a Symbol and DbValue
+      #
+      # ```
+      # Query.where(:name, "Conan")
+      # ```
       def self.where(where_sym : Symbol, param : DbValue)
         self.new.where(where_sym, param)
       end
 
+      # Query WHERE IN with a Symbol and Array(DbValue)
+      #
+      # ```
+      # Query.where(:name, ["Conan", "Zeus"])
+      # ```
       def self.where(where_sym : Symbol, params : Array(DbValue | PkeyValue))
         self.new.where(where_sym, params)
       end
 
       # Key => Value pair(s) used in query `OR WHERE`
+      #
+      # ```
+      # Query.where(name: "Thor", age: 60)
+      # ```
       def self.or_where(**or_wheres)
         self.new.or_where(**or_wheres)
       end
 
+      # Join query with *join_associations*
+      #
+      # ```
+      # Query.join([:posts, :projects])
+      # ```
       def self.join(join_associations : Array(Symbol))
         self.new.join(join_associations)
       end
 
+      # Join query with *join_association*
+      #
+      # ```
+      # Query.join(:posts)
+      # ```
       def self.join(join_association : Symbol)
         self.new.join(join_association)
       end
 
-      def self.join(join_associations : Array(Symbol))
-        self.new.join(klass, joins)
-      end
-
+      # Preload assoications
+      #
+      # ```
+      # Query.preload([:posts, :projects])
+      # ```
       def self.preload(preload_associations : Array(Symbol))
         self.new.preload(preload_associations)
       end
 
+      # Preload assoication
+      #
+      # ```
+      # Query.preload(:posts)
+      # ```
       def self.preload(preload_association : Symbol)
         self.new.preload(preload_association)
       end
 
-      # Field to order by
+      # Field to ORDER BY
+      #
+      # ```
+      # Query.order_by("last_name ASC")
+      # ```
       def self.order_by(order : String)
         self.new.order_by(order)
       end
 
-      # Query Limit
+      # Query LIMIT
+      #
+      # ```
+      # Query.limit(50)
+      # ```
       def self.limit(lim : Int32 | Int64)
         self.new.limit(lim)
       end
 
-      # Query offset
+      # Query OFFSET
+      #
+      # ```
+      # Query.offset(20)
+      # ```
       def self.offset(off : Int32 | Int64)
         self.new.offset(off)
       end
@@ -84,78 +138,135 @@ module Crecto
         @selects = ["*"]
       end
 
-      # :nodoc:
-      def select(selects)
-        @selects = string
+      # Fields to select, separated by comma.  Default is "*"
+      #
+      # ```
+      # Query.select(['id', 'name'])
+      # ```
+      def select(selects : Array(String))
+        @selects = selects
         self
       end
 
-      # :nodoc:
+      # Key => Value pair(s) used in query `WHERE`
+      #
+      # ```
+      # Query.where(name: "Thor", age: 60)
+      # ```
       def where(**wheres)
         wheres = wheres.to_h
-        # w = {} of Symbol => DbValue | PkeyValue | Array(DbValue | PkeyValue)
-        # w[wheres.first_key] = wheres.first_value.as(DbValue | PkeyValue | Array(DbValue | PkeyValue))
         @wheres.push(Hash.zip(wheres.keys, wheres.values))
         self
       end
 
+      # Query where with a string
+      #
+      # ```
+      # Query.where("users.id > ?", [10])
+      # ```
       def where(where_string : String, params : Array(DbValue))
         @wheres.push({clause: where_string, params: params.map { |p| p.as(DbValue) }})
         self
       end
 
+      # Query where with a Symbol and DbValue
+      #
+      # ```
+      # Query.where(:name, "Conan")
+      # ```
       def where(where_sym : Symbol, param : DbValue)
         @wheres.push(Hash.zip([where_sym], [param]))
         self
       end
 
+      # Query WHERE IN with a Symbol and Array(DbValue)
+      #
+      # ```
+      # Query.where(:name, ["Conan", "Zeus"])
+      # ```
       def where(where_sym : Symbol, params : Array(DbValue))
         w = {} of Symbol => Array(DbValue)
         w[where_sym] = params.map { |x| x.as(DbValue) }
         @wheres.push(w)
         self
       end
 
+      # Key => Value pair(s) used in query `OR WHERE`
+      #
+      # ```
+      # Query.where(name: "Thor", age: 60)
+      # ```
       def or_where(**or_wheres)
         or_wheres = or_wheres.to_h
         @or_wheres.push or_wheres
         self
       end
 
-      # :nodoc:
+      # Join query with *join_associations*
+      #
+      # ```
+      # Query.join([:posts, :projects])
+      # ```
       def join(join_associations : Array(Symbol))
         @joins += join_associations
         self
       end
 
+      # Join query with *join_association*
+      #
+      # ```
+      # Query.join(:posts)
+      # ```
       def join(join_association : Symbol)
         @joins.push(join_association)
         self
       end
 
+      # Preload assoications
+      #
+      # ```
+      # Query.preload([:posts, :projects])
+      # ```
       def preload(preload_associations : Array(Symbol))
         @preloads += preload_associations
         self
       end
 
+      # Preload assoication
+      #
+      # ```
+      # Query.preload(:posts)
+      # ```
       def preload(preload_association : Symbol)
         @preloads.push(preload_association)
         self
       end
 
-      # :nodoc:
+      # Field to ORDER BY
+      #
+      # ```
+      # Query.order_by("last_name ASC")
+      # ```
       def order_by(order)
         @order_bys.push(order)
         self
       end
 
-      # :nodoc:
+      # Query LIMIT
+      #
+      # ```
+      # Query.limit(50)
+      # ```
       def limit(lim)
         @limit = limit
         self
       end
 
-      # :nodoc:
+      # Query OFFSET
+      #
+      # ```
+      # Query.offset(20)
+      # ```
       def offset(off)
         @offset = off
         self