path_component.rb in wolverine-0.2.3

- old
+ new

@@ -1,13 +1,30 @@
 module Wolverine
+  # A {PathComponent} represents either the +Wolverine.config.script_path+
+  # directory, or a subdirectory of it. Calling (nearly) any method on it will
+  # cause it to look in the filesystem at the location it refers to for a file
+  # or directory matching the method name. These results are cached.
+  #
+  # Calling a method that maps to a directory will return a new {PathComponent}
+  # with a +path+ referring to that directory.
+  #
+  # Calling a method that maps to a file (with +'.lua'+ automatically appended
+  # to the name) will load the file via {Script} and call it with the
+  # arugments passed, returning the result ({method_missing}).
   class PathComponent
     class MissingTemplate < StandardError ; end
 
+    # @param path [Pathname] full path to the current file or directory
     def initialize path
       @path = path
     end
 
+    # @param sym [Symbol] the file or directory to look up and execute
+    # @param args [*Objects] arguments to pass to the {Script}, if +sym+ resolves to a lua file
+    # @return [PathComponent, Object] A new, nested {PathComponent} if +sym+ resolves to
+    #   a directory, or an execution result if it resolves to a file.
+    # @raise [MissingTemplate] if +sym+ maps to neither a directory or a file
     def method_missing sym, *args
       create_method sym, *args
       send sym, *args
     end
 
@@ -48,6 +65,6 @@
       metaclass.send(:define_method, sym, &block)
     end
 
   end
 
-end
\ No newline at end of file
+end