Permalink
Browse files

Port inline docs to yard

  • Loading branch information...
1 parent 7b55c3a commit 3b088e0ecef6b9269c25f1a700096c8cf4954b0a @mynyml committed Feb 9, 2010
View
@@ -21,6 +21,6 @@ Signal.trap('INT' ) { abort("\n") } # Ctrl-C
# --------------------------------------------------
def yard
print "Updating yardocs... "; STDOUT.flush
- YARD::CLI::Yardoc.run *%w( -o doc/yard --readme README.md --markup rdoc - LICENSE TODO.txt )
+ YARD::CLI::Yardoc.run *%w( -o doc/yard --readme README.md --markup markdown - LICENSE TODO.txt )
print "done\n"
end
View
@@ -5,12 +5,12 @@
# user defined action whenever an observed file is modified. Its most typical
# use is continuous testing.
#
-# Usage:
+# See README for more details
#
-# # on command line, from project's root dir
-# $ watchr path/to/script
+# @example
#
-# See README for more details
+# # on command line, from project's root dir
+# $ watchr path/to/script
#
module Watchr
VERSION = '0.5.9'
@@ -35,63 +35,67 @@ class << self
attr_accessor :options
attr_accessor :handler
- # backwards compatibility
+ # @deprecated
def version #:nodoc:
Watchr::VERSION
end
# Options proxy.
#
# Currently supported options:
- # * debug<Boolean> Debugging state. More verbose.
#
- # ===== Examples
+ # * debug[Boolean] Debugging state. More verbose.
+ #
+ # @example
#
- # Watchr.options.debug #=> false
- # Watchr.options.debug = true
+ # Watchr.options.debug #=> false
+ # Watchr.options.debug = true
#
- # ===== Returns
- # options<Struct>:: options proxy.
+ # @return [Struct]
+ # options proxy.
#
- #--
- # On first use, initialize the options struct and default option values.
def options
@options ||= Struct.new(:debug).new
@options.debug ||= false
@options
end
- # Outputs formatted debug statement to stdout, only if ::options.debug is true
+ # Outputs formatted debug statement to stdout, only if `::options.debug` is true
+ #
+ # @example
+ #
+ # Watchr.options.debug = true
+ # Watchr.debug('im in ur codes, notifayinin u')
#
- # ===== Examples
+ # #outputs: "[watchr debug] im in ur codes, notifayinin u"
#
- # Watchr.options.debug = true
- # Watchr.debug('im in ur codes, notifayinin u')
+ # @param [String] message
+ # debug message to print
#
- # outputs: "[watchr debug] im in ur codes, notifayinin u"
+ # @return [nil]
#
- def debug(str)
- puts "[watchr debug] #{str}" if options.debug
+ def debug(msg)
+ puts "[watchr debug] #{msg}" if options.debug
end
# Detect current OS and return appropriate handler.
#
- # ===== Examples
+ # @example
#
- # Config::CONFIG['host_os'] #=> 'linux-gnu'
- # Watchr.handler #=> Watchr::EventHandler::Unix
+ # Config::CONFIG['host_os'] #=> 'linux-gnu'
+ # Watchr.handler #=> Watchr::EventHandler::Unix
#
- # Config::CONFIG['host_os'] #=> 'cygwin'
- # Watchr.handler #=> Watchr::EventHandler::Portable
+ # Config::CONFIG['host_os'] #=> 'cygwin'
+ # Watchr.handler #=> Watchr::EventHandler::Portable
#
- # ENV['HANDLER'] #=> 'unix'
- # Watchr.handler #=> Watchr::EventHandler::Unix
+ # ENV['HANDLER'] #=> 'unix'
+ # Watchr.handler #=> Watchr::EventHandler::Unix
#
- # ENV['HANDLER'] #=> 'portable'
- # Watchr.handler #=> Watchr::EventHandler::Portable
+ # ENV['HANDLER'] #=> 'portable'
+ # Watchr.handler #=> Watchr::EventHandler::Portable
#
- # ===== Returns
- # handler<Class>:: handler class for current architecture
+ # @return [Class]
+ # handler class for current architecture
#
def handler
@handler ||=
View
@@ -2,55 +2,58 @@ module Watchr
# The controller contains the app's core logic.
#
- # ===== Examples
+ # @example
#
- # script = Watchr::Script.new(file)
- # contrl = Watchr::Controller.new(script)
- # contrl.run
+ # script = Watchr::Script.new(file)
+ # contrl = Watchr::Controller.new(script, Watchr.handler.new)
+ # contrl.run
#
- # Calling <tt>#run</tt> will enter the listening loop, and from then on every
- # file event will trigger its corresponding action defined in <tt>script</tt>
+ # # Calling `run` will enter the listening loop, and from then on every
+ # # file event will trigger its corresponding action defined in `script`
#
- # The controller also automatically adds the script's file itself to its list
- # of monitored files and will detect any changes to it, providing on the fly
- # updates of defined rules.
+ # # The controller also automatically adds the script's file to its list of
+ # # monitored files and will detect any changes to it, providing on the fly
+ # # updates of defined rules.
#
class Controller
- # Creates a controller object around given <tt>script</tt>
+ # Create a controller object around given `script`
#
- # ===== Parameters
- # script<Script>:: The script object
- # handler<EventHanlder::Base>:: The filesystem event handler
+ # @param [Script] script
+ # The script object
+ #
+ # @param [EventHandler::Base] handler
+ # The filesystem event handler
+ #
+ # @see Watchr::Script
+ # @see Watchr.handler
#
def initialize(script, handler)
- @script = script
- @handler = handler
-
+ @script, @handler = script, handler
@handler.add_observer(self)
Watchr.debug "using %s handler" % handler.class.name
end
- # Enters listening loop.
- #
- # Will block control flow until application is explicitly stopped/killed.
- #
+ # Enter listening loop. Will block control flow until application is
+ # explicitly stopped/killed.
def run
@script.parse!
@handler.listen(monitored_paths)
rescue Interrupt
end
- # Callback for file events.
+ # Callback for file events
#
# Called while control flow is in listening loop. It will execute the
# file's corresponding action as defined in the script. If the file is the
# script itself, it will refresh its state to account for potential changes.
#
- # ===== Parameters
- # path<Pathname, String>:: path that triggered event
- # event_type<Symbol>:: event type
+ # @param [Pathname, String] path
+ # path that triggered the event
+ #
+ # @param [Symbol] event
+ # event type
#
def update(path, event_type = nil)
path = Pathname(path).expand_path
@@ -68,8 +71,8 @@ def update(path, event_type = nil)
# Basically this means all paths below current directoly recursivelly that
# match any of the rules' patterns, plus the script file.
#
- # ===== Returns
- # paths<Array[Pathname]>:: List of monitored paths
+ # @return [Array<Pathname>]
+ # list of all monitored paths
#
def monitored_paths
paths = Dir['**/*'].select do |path|
@@ -2,44 +2,53 @@
module Watchr
module EventHandler
- class AbstractMethod < Exception #:nodoc:
- end
- # Base functionality mixin meant to be included in specific event handlers.
+ # @private
+ class AbstractMethod < Exception; end
+
+ # Base functionality mixin, meant to be included in specific event handlers.
+ #
+ # @abstract
module Base
include Observable
# Notify that a file was modified.
#
- # ===== Parameters
- # path<Pathname, String>:: full path or path relative to current working directory
- # event_type<Symbol>:: event type.
- #--
- # #changed and #notify_observers are Observable methods
+ # @param [Pathname, String] path
+ # full path or path relative to current working directory
+ #
+ # @param [Symbol] event
+ # event type.
+ #
+ # @return [undefined]
+ #
def notify(path, event_type = nil)
changed(true)
notify_observers(path, event_type)
end
- # Begin watching given paths and enter listening loop. Called by the controller.
+ # Begin watching given paths and enter listening loop. Called by the
+ # controller.
#
- # Abstract method
+ # @param [Array<Pathname>] monitored_paths
+ # list of paths the application is currently monitoring.
#
- # ===== Parameters
- # monitored_paths<Array(Pathname)>:: list of paths the application is currently monitoring.
+ # @return [undefined]
#
+ # @abstract
def listen(monitored_paths)
raise AbstractMethod
end
# Called by the controller when the list of paths monitored by wantchr
# has changed. It should refresh the list of paths being watched.
#
- # Abstract method
+ # @param [Array<Pathname>] monitored_paths
+ # list of paths the application is currently monitoring.
#
- # ===== Parameters
- # monitored_paths<Array(Pathname)>:: list of paths the application is currently monitoring.
+ # @return [undefined]
#
+ # @abstract
def refresh(monitored_paths)
raise AbstractMethod
end
@@ -11,18 +11,33 @@ def initialize
#
# Will block control flow until application is explicitly stopped/killed.
#
+ # @param [Array<Pathname>] monitored_paths
+ # list of paths the application is currently monitoring.
+ #
+ # @return [undefined]
+ #
def listen(monitored_paths)
@monitored_paths = monitored_paths
loop { trigger; sleep(1) }
end
# See if an event occured, and if so notify observers.
- def trigger #:nodoc:
+ #
+ # @return [undefined]
+ #
+ # @private
+ def trigger
path, type = detect_event
notify(path, type) unless path.nil?
end
# Update list of monitored paths.
+ #
+ # @param [Array<Pathname>] monitored_paths
+ # list of paths the application is currently monitoring.
+ #
+ # @return [undefined]
+ #
def refresh(monitored_paths)
@monitored_paths = monitored_paths
end
@@ -34,13 +49,12 @@ def refresh(monitored_paths)
# If the latest mtime is more recent than the reference mtime, return
# that file's path.
#
- # ===== Returns
- # path and type of event if event occured, nil otherwise
+ # @return [[Pathname, Symbol]]
+ # path and type of event if event occured, nil otherwise
+ #
+ # @todo improve ENOENT error handling
#
- #--
- # OPTIMIZE, REFACTOR
- # TODO fix/figure out ENOENT error
- def detect_event
+ def detect_event # OPTIMIZE, REFACTOR
@monitored_paths.each do |path|
return [path, :deleted] unless path.exist?
end
Oops, something went wrong.

0 comments on commit 3b088e0

Please sign in to comment.