Add YARD documentation

lib/pairtree.rb

@@ -12,6 +12,13 @@ class VersionMismatch < Exception; end
 
   SPEC_VERSION = 0.1
 
+  ##
+  # Instantiate a pairtree at a given path location
+  # @param [String] path The path in which the pairtree resides
+  # @param [Hash] args Pairtree options
+  # @option args [String] :prefix (nil) the identifier prefix used throughout the pairtree
+  # @option args [String] :version (Pairtree::SPEC_VERSION) the version of the pairtree spec that this tree conforms to
+  # @option args [Boolean] :create (false) if true, create the pairtree and its directory structure if it doesn't already exist
   def self.at path, args = {}
     args = { :prefix => nil, :version => nil, :create => false }.merge(args)
     args[:version] ||= SPEC_VERSION

lib/pairtree/identifier.rb

@@ -2,18 +2,31 @@ module Pairtree
   class Identifier
     ENCODE_REGEX = Regexp.compile("[\"*+,<=>?\\\\^|]|[^\x21-\x7e]", nil, 'u')
     DECODE_REGEX = Regexp.compile("\\^(..)", nil, 'u')
+
+    ##
+    # Encode special characters within an identifier
+    # @param [String] id The identifier
     def self.encode id
       id.gsub(ENCODE_REGEX) { |c| char2hex(c) }.tr('/:.', '=+,')
     end
 
+    ##
+    # Decode special characters within an identifier
+    # @param [String] id The identifier
     def self.decode id
       id.tr('=+,', '/:.').gsub(DECODE_REGEX) { |h| hex2char(h) } 
     end
 
+    ##
+    # Convert a character to its pairtree hexidecimal representation
+    # @param [Char] c The character to convert
     def self.char2hex c
       c.unpack('H*')[0].scan(/../).map { |x| "^#{x}"}
     end
 
+    ##
+    # Convert a pairtree hexidecimal string to its character representation
+    # @param [String] h The hexidecimal string to convert
     def self.hex2char h
        '' << h.delete('^').hex
     end

lib/pairtree/root.rb

@@ -5,6 +5,11 @@ class Root
 
     attr_reader :root, :prefix
 
+    ##
+    # @param [String] root The pairtree_root directory within the pairtree home
+    # @param [Hash] args Pairtree options
+    # @option args [String] :prefix (nil) the identifier prefix used throughout the pairtree
+    # @option args [String] :version (Pairtree::SPEC_VERSION) the version of the pairtree spec that this tree conforms to
     def initialize root, args = {}
       @root = root
 
@@ -14,9 +19,12 @@ def initialize root, args = {}
       @options = args
     end
 
+    ##
+    # Get a list of valid existing identifiers within the pairtree
+    # @return [Array]
     def list          
       objects = []
-      return [] unless pairtree_root? @root
+      return [] unless File.directory? @root
 
       Dir.chdir(@root) do
         possibles = Dir['**/?'] + Dir['**/??']
@@ -28,45 +36,68 @@ def list
       objects.map { |x| @prefix + Pairtree::Path.path_to_id(x) }
     end
 
+    ##
+    # Get the path containing the pairtree_root
+    # @return [String]
     def path
       File.dirname(root)
     end
 
+    ##
+    # Get the full path for a given identifier (whether it exists or not)
+    # @param [String] id The full, prefixed identifier
+    # @return [String]
     def path_for id
       unless id.start_with? @prefix
         raise IdentifierError, "Identifier must start with #{@prefix}"
       end
       path_id = id[@prefix.length..-1]
       File.join(@root, Pairtree::Path.id_to_path(path_id))
     end
-
+
+    ##
+    # Determine if a given identifier exists within the pairtree
+    # @param [String] id The full, prefixed identifier
+    # @return [Boolean]
     def exists? id
       File.directory?(path_for(id))
     end
 
+    ##
+    # Get an existing ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Pairtree::Obj] The object encapsulating the identifier's ppath
     def get id
       Pairtree::Obj.new path_for(id)
     end
     alias_method :[], :get
 
+    ##
+    # Create a new ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Pairtree::Obj] The object encapsulating the newly created ppath
     def mk id
       FileUtils.mkdir_p path_for(id)
       get(id)
     end
 
+    ##
+    # Delete a ppath
+    # @param [String] id The full, prefixed identifier
+    # @return [Boolean]
     def purge! id
       if exists?(id)
         Pairtree::Path.remove!(path_for(id))
       end
       not exists?(id)
     end
 
-    def pairtree_root
-      Dir.new @root
-    end
-
-    def pairtree_root? path = @root
-      File.directory? path
+    ##
+    # Get the version of the pairtree spec that this pairtree conforms to
+    # @return [String]
+    def pairtree_version
+      @options[:version]
     end
+
   end
 end

pairtree.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.email            = %q{[email protected]}
   s.files            = `git ls-files`.split("\n")
   s.test_files       = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.extra_rdoc_files = ["LICENSE.txt", "README.rdoc"]
+  s.extra_rdoc_files = ["LICENSE.txt", "README.textile"]
   s.executables      = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths    = ["lib"]