Permalink
Browse files

Add more YARD docs including Cypher/Rules closes #181

  • Loading branch information...
1 parent f0f4023 commit d321a276847faaea07ba13f93f7061c469006b50 @andreasronge andreasronge committed Apr 19, 2012
View
@@ -0,0 +1,2 @@
+--title 'Neo4j.rb API Documentation'
+--no-private
@@ -4,10 +4,13 @@ module Rails
# in a Railsy way. This typically means not writing anything to the DB until the
# object is saved (after validation).
#
- # Externally, when we talk about properties (e.g. #property?, #property_names, #properties),
+ # Externally, when we talk about properties (e.g. {#property?}, {#property_names}),
# we mean all of the stored properties for this object include the 'hidden' props
# with underscores at the beginning such as _neo_id and _classname. When we talk
# about attributes, we mean all the properties apart from those hidden ones.
+ #
+ # This mixin defines a number of class methods, see #{ClassMethods}.
+ #
module Attributes
extend ActiveSupport::Concern
extend TxMethods
@@ -47,13 +50,17 @@ def self.inherited(sub_klass)
end
end
+ # Is called when a node neo4j entity is created and we need to save attributes
+ # @private
def init_on_create(*)
self._classname = self.class.to_s
write_default_attributes
write_changed_attributes
clear_changes
end
+ # Setup this mixins instance variables
+ # @private
def initialize_attributes(attributes)
@_properties = {}
@_properties_before_type_cast={}
@@ -88,13 +95,14 @@ def update_attributes(attributes)
end
tx_methods :update_attributes
- # Same as #update_attributes, but raises an exception if saving fails.
+ # Same as {#update_attributes}, but raises an exception if saving fails.
def update_attributes!(attributes)
self.attributes = attributes
save!
end
tx_methods :update_attributes!
+ # @private
def reset_attributes
@_properties = {}
end
View
@@ -3,10 +3,12 @@ module Rails
class RecordNotFoundError < StandardError
end
+ # Defines {ClassMethods}
module Finders
extend ActiveSupport::Concern
+ # @private
def reachable_from_ref_node?
# All relationships are reachable
respond_to?(:_java_rel) || Neo4j::Algo.all_path(self.class.ref_node_for_class, self).outgoing(self.class).outgoing(:_all).first != nil
@@ -16,8 +18,29 @@ def reachable_from_ref_node?
rule(:_all, :functions => Neo4j::Wrapper::Rule::Functions::Size.new) if respond_to?(:rule)
end
+ # Defines the #{#find} method. When declaring properties with index a number of finder methods will be generated,
+ # similar to active record, example +find_by_<property_name>+, +find_or_create_by_<property_name>. +all_by_<property_name>+
+ #
+ # @example find_or_create_by
+ # class Person < Neo4j::Rails::Model
+ # property :age, :type => Fixnum
+ # end
+ #
+ # Person.find_by_age(42)
+ # Person.find_or_create_by
+ # Person.find_or_create_by!(:age => 'bla')
+ #
+ # @example find all
+ # Person.all_by_age
+ # Person.all(:name => 'bla')
+ # Person.all('name: "bla"') # lucene query syntax
+ #
+ # @see Neo4j::Rails::Attributes::ClassMethods#property
+ # @see #find
+ #
module ClassMethods
+ # @private
def index_prefix
return "" unless Neo4j.running?
return "" unless respond_to?(:ref_node_for_class)
@@ -26,6 +49,7 @@ def index_prefix
prefix ? prefix + "_" : ""
end
+ # @private
# overwrite the index method to add find_by_xxx class methods
def index(*args)
field = args.first
View
@@ -1,14 +1,15 @@
module Neo4j
module Rails
+ # Defines class methods, see {ClassMethods}
module HasN
extend ActiveSupport::Concern
module ClassMethods
# Create a number of methods similar to active record has_many.
- # The first one returns an Neo4j::Rails::Relationships::NodesDSL
+ # The first one returns an {Neo4j::Rails::Relationships::NodesDSL}
# the second generate method (with the _rels postfix) returns a
- # Neo4j::Rails::Relationships::RelsDSL
+ # {Neo4j::Rails::Relationships::RelsDSL}
#
# See also Neo4j::NodeMixin#has_n which only work with persisted relationships.
#
View
@@ -1,20 +1,39 @@
module Neo4j
module Rails
# Makes Neo4j nodes and relationships behave like active record objects.
- # That means for example that you don't have to care about transactions since they will be
- # automatically be created when needed. Validation, Callbacks etc. are also supported.
+ # That means for example that you don't (normally) have to care about transactions since they will be
+ # automatically be created when needed. {Neo4j::Rails::Validation}, {Neo4j::Rails::Callbacks} etc. are also supported.
#
- # @example Traverse
+ # @example Create a node (learn more - see {Neo4j::Rails::Persistence})
+ # class Company < Neo4j::Rails::Model
+ # end
+ # Company.new.save
+ # Company.save
+ # Company.save(:name => 'Foo Ab')
+ #
+ # @example Declare properties (learn more - see {Neo4j::Rails::Attributes})
+ #
+ # class Company < Neo4j::Rails::Model
+ # property :data
+ # property :revenue, :type => :Float
+ # end
+ #
+ # c = Company.new(:data => false, :type => '2123123.23')
+ # c.data = "changed type"
+ # c.revenue = 123124 # will always be converted
+ #
+ # @example Creating and Navigating Relationships (learn more - see {Neo4j::Rails::Relationships})
# class Person < Neo4j::Rails::Model
# end
#
- # person = Person.find(...)
- # person.outgoing(:foo) << Person.create
+ # person = Person.new
+ # person.outgoing(:foo) << Person.new
# person.save!
# person.outgoing(:foo).depth(:all)...
# person.outgoing(:friends).map{|f| f.outgoing(:knows).to_a}.flatten
+ # person.rels(:outgoing, :foo).first.end_node #=> the other node
#
- # @example Declared Relationships: has_n and has_one
+ # @example Declared Relationships (learn more - see {Neo4j::Rails::HasN::ClassMethods})
#
# class Person < Neo4j::Rails::Model
# end
@@ -25,9 +44,9 @@ module Rails
# end
#
# Person.new.foo << other_node
- # Person.friends.build(:name => 'kalle')
+ # Person.friends.build(:name => 'kalle').save
#
- # @example Declared Properties and Index
+ # @example Searching with Lucene Index (learn more - see {Neo4j::Rails::Finders::ClassMethods})
#
# class Person < Neo4j::Rails::Model
# property :name
@@ -37,7 +56,32 @@ module Rails
# Person.create(:name => 'kalle', :age => 42, :undeclared_prop => 3.14)
# Person.find_by_age(42)
#
- # @example Callbacks
+ # @example Searching with Cypher (learn more - {Neo4j-core}[http://rdoc.info/github/andreasronge/neo4j-core/file/README.rdoc])
+ #
+ # Monster.all.query(:strength => 17).first #=> a node/Neo4j::Rails::Model
+ # Monster.all.query(:strength => 17).to_s #=> "START n0=node(42) MATCH ..."
+ # Neo4j.query{Neo4j.rb cypher DSL}
+ # dungeon.monsters.query(:name => 'Ghost', :strength => 10) # all monsters with those properties
+ # dungeon.monsters(:name => 'Ghost', :strength => 10) # same as above
+ # dungeon.monsters { |m| m[:name] == 'Ghost'] & m[:strength] == 16} # same as above
+ #
+ # @example Rules and Cypher (learn more {Neoj::Wrapper::Rule::ClassMethods}[http://rdoc.info/github/andreasronge/neo4j-wrapper/Neo4j/Wrapper/Rule/ClassMethods] )
+ # class Dungeon < Neo4j::Rails::Model
+ # has_n(:monsters).to(Monster)
+ # end
+ #
+ # class Monster < Neo4j::Rails::Model
+ # rule(:dangerous) { |m| m[:strength] > 15 }
+ # end
+ #
+ # class Room < Neo4j::Rails::Model
+ # has_n(:monsters).to(Monster)
+ # end
+ #
+ # @dungeon.monsters.dangerous { |m| rooms = m.incoming(Room.monsters); rooms } # returns rooms we should avoid
+ # @dungeon.monsters{|m| ret(m).asc(m[:strength])} # return the monsters nodes sorted by strength
+ #
+ # @example Callbacks (learn more - see #{Neo4j::Rails::Callbacks})
#
# class Person < Neo4j::Rails::Model
# before_save :do_something
@@ -1,62 +1,65 @@
module Neo4j
module Rails
+ # Defines the create, delete and update methods.
+ # @see ClassMethods class methods when including this module
module Persistence
extend ActiveSupport::Concern
extend TxMethods
# Persist the object to the database. Validations and Callbacks are included
- # by default but validation can be disabled by passing :validate => false
- # to #save.
+ # by default but validation can be disabled by passing <tt>:validate => false</tt>
+ # to <tt>save</tt>. Creates a new transaction.
+ # @param (see Neo4j::Rails::Validations#save)
+ # @return [Boolean] true if it was persisted
+ # @see Neo4j::Rails::Validations Neo4j::Rails::Validations - for the :validate parameter
+ # @see Neo4j::Rails::Callbacks Neo4j::Rails::Callbacks - for callbacks
def save(*)
create_or_update
end
tx_methods :save
# Persist the object to the database. Validations and Callbacks are included
# by default but validation can be disabled by passing :validate => false
- # to #save!.
+ # to #save! Creates a new transaction.
#
- # Raises a RecordInvalidError if there is a problem during save.
+ # @raise a RecordInvalidError if there is a problem during save.
+ # @param (see Neo4j::Rails::Validations#save)
+ # @return nil
+ # @see #save
+ # @see Neo4j::Rails::Validations Neo4j::Rails::Validations - for the :validate parameter
+ # @see Neo4j::Rails::Callbacks Neo4j::Rails::Callbacks - for callbacks
def save!(*args)
unless save(*args)
raise RecordInvalidError.new(self)
end
end
- def update
- write_changed_attributes
- clear_changes
- true
- end
-
-
-
# Removes the node from Neo4j and freezes the object.
def destroy
delete
freeze
end
# Same as #destroy but doesn't run destroy callbacks and doesn't freeze
- # the object
+ # the object. Creates a new transaction
def delete
del unless new_record? || destroyed?
set_deleted_properties
end
tx_methods :delete
- # Returns true if the object was destroyed.
+ # Returns +true+ if the object was destroyed.
def destroyed?
@_deleted || (!new_record? && !self.class.load_entity(neo_id))
end
- # Returns if the record is persisted, i.e. it’s not a new record and it was not destroyed
+ # Returns +true+ if the record is persisted, i.e. it’s not a new record and it was not destroyed
def persisted?
!new_record? && !destroyed?
end
- # Returns true if the record hasn't been saved to Neo4j yet.
+ # Returns +true+ if the record hasn't been saved to Neo4j yet.
def new_record?
_java_entity.nil?
end
@@ -117,6 +120,13 @@ def destroy_all
end
protected
+
+ def update
+ write_changed_attributes
+ clear_changes
+ true
+ end
+
def create_or_update
result = persisted? ? update : create
unless result != false
@@ -1,7 +1,8 @@
module Neo4j
module Rails
- # This module overrides the Neo4j::Core::Rels module so that it can handle unpersisted relationships.
+ # This module overrides the {Neo4j::Core::Rels}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j/Core/Rels] and {Neo4j::Core::Traversal}[http://rdoc.info/github/andreasronge/neo4j-core/Neo4j/Core/Traversal]
+ # modules so that it can handle unpersisted relationships of depth one.
#
module Relationships
extend ActiveSupport::Concern
@@ -1,14 +1,20 @@
module Neo4j
module Rails
+ # This mixin replace the original save method and performs validation before the save.
module Validations
include ActiveModel::Validations
+ # Implements the ActiveModel::Validation hook method.
+ # @see http://rubydoc.info/docs/rails/ActiveModel/Validations:read_attribute_for_validation
def read_attribute_for_validation(key)
respond_to?(key) ? send(key) : self[key]
end
# The validation process on save can be skipped by passing false. The regular Model#save method is
# replaced with this when the validations module is mixed in, which it is by default.
+ # @param [Hash] options the options to create a message with.
+ # @option options [true, false] :validate if false no validation will take place
+ # @return [Boolean] true if it saved it successfully
def save(options={})
result = perform_validations(options) ? super : false
if !result
@@ -17,6 +23,7 @@ def save(options={})
result
end
+ # @return [Boolean] true if valid
def valid?(context = nil)
context ||= (new_record? ? :create : :update)
super(context)

0 comments on commit d321a27

Please sign in to comment.