From: Steve Coast <steve@asklater.com>
Date: Thu, 24 Jan 2008 13:04:04 +0000 (+0000)
Subject: Some node documentation
X-Git-Tag: live~7938
X-Git-Url: https://git.openstreetmap.org/rails.git/commitdiff_plain/9328e84ba18070c73975c64e84f6bcf2890b87dc

Some node documentation
---

diff --git a/app/controllers/node_controller.rb b/app/controllers/node_controller.rb
index 1aef6a8a5..edc3675e5 100644
--- a/app/controllers/node_controller.rb
+++ b/app/controllers/node_controller.rb
@@ -1,3 +1,5 @@
+# The NodeController is the RESTful interface to Node objects
+
 class NodeController < ApplicationController
   require 'xml/libxml'
 
@@ -7,6 +9,7 @@ class NodeController < ApplicationController
   before_filter :check_read_availability, :except => [:create, :update, :delete]
   after_filter :compress_output
 
+  # Create a node from XML.
   def create
     if request.put?
       node = Node.from_xml(request.raw_post, true)
@@ -25,6 +28,7 @@ class NodeController < ApplicationController
     end
   end
 
+  # Dump the details on a node given in params[:id]
   def read
     begin
       node = Node.find(params[:id])
@@ -39,6 +43,7 @@ class NodeController < ApplicationController
     end
   end
 
+  # Update a node from given XML
   def update
     begin
       node = Node.find(params[:id])
@@ -61,6 +66,8 @@ class NodeController < ApplicationController
     end
   end
 
+  # Delete a node. Doesn't actually delete it, but retains its history in a wiki-like way.
+  # FIXME remove all the fricking SQL
   def delete
     begin
       node = Node.find(params[:id])
@@ -85,6 +92,7 @@ class NodeController < ApplicationController
     end
   end
 
+  # WTF does this do?
   def nodes
     ids = params['nodes'].split(',').collect { |n| n.to_i }
 
diff --git a/app/models/node.rb b/app/models/node.rb
index 08a675b43..2a073f542 100644
--- a/app/models/node.rb
+++ b/app/models/node.rb
@@ -1,3 +1,5 @@
+# The node model represents a current existing node, that is, the latest version. Use OldNode for historical nodes.
+
 class Node < GeoRecord
   require 'xml/libxml'
 
@@ -12,16 +14,20 @@ class Node < GeoRecord
   has_many :way_nodes
   belongs_to :user
  
+  # Sanity check the latitude and longitude and add an error if it's broken
   def validate_position
     errors.add_to_base("Node is not in the world") unless in_world?
   end
 
+  # Is this node withing -90 > latitude > 90 and -180 > longitude > 180>
+  # * returns true/false
   def in_world?
     return false if self.lat < -90 or self.lat > 90
     return false if self.lon < -180 or self.lon > 180
     return true
   end
 
+  # Read in xml as text and return it's Node object representation
   def self.from_xml(xml, create=false)
     begin
       p = XML::Parser.new
@@ -67,6 +73,7 @@ class Node < GeoRecord
     return node
   end
 
+  # Save this node with the appropriate OldNode object to represent it's history.
   def save_with_history!
     Node.transaction do
       self.timestamp = Time.now
@@ -76,12 +83,14 @@ class Node < GeoRecord
     end
   end
 
+  # Turn this Node in to a complete OSM XML object with <osm> wrapper
   def to_xml
     doc = OSM::API.new.get_xml_doc
     doc.root << to_xml_node()
     return doc
   end
 
+  # Turn this Node in to an XML Node without the <osm> wrapper.
   def to_xml_node(user_display_name_cache = nil)
     el1 = XML::Node.new 'node'
     el1['id'] = self.id.to_s
@@ -112,6 +121,7 @@ class Node < GeoRecord
     return el1
   end
 
+  # Return the node's tags as a Hash of keys and their values
   def tags_as_hash
     hash = {}
     Tags.split(self.tags) do |k,v|
@@ -119,5 +129,4 @@ class Node < GeoRecord
     end
     hash
   end
-
 end