From 1234af557bfe184fbdd5d40076c41f0feee737de Mon Sep 17 00:00:00 2001 From: drbrain Date: Mon, 16 May 2011 21:53:12 +0000 Subject: * lib/observer.rb: Improve documentation. Patch by David Copeland. [Ruby 1.9 - Bug #4707] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31599 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/observer.rb | 73 ++++++++++++++++++++++++++++++++------------------------- 1 file changed, 41 insertions(+), 32 deletions(-) (limited to 'lib/observer.rb') diff --git a/lib/observer.rb b/lib/observer.rb index ee3f01b793..a5d0dc0f4e 100644 --- a/lib/observer.rb +++ b/lib/observer.rb @@ -1,33 +1,34 @@ # -# observer.rb implements the _Observer_ object-oriented design pattern. The +# Implementation of the _Observer_ object-oriented design pattern. The # following documentation is copied, with modifications, from "Programming # Ruby", by Hunt and Thomas; http://www.rubycentral.com/book/lib_patterns.html. # -# == About -# -# The Observer pattern, also known as Publish/Subscribe, provides a simple +# See Observable for more info. + +# The Observer pattern (also known as publish/subscribe) provides a simple # mechanism for one object to inform a set of interested third-party objects # when its state changes. # # == Mechanism # -# In the Ruby implementation, the notifying class mixes in the +Observable+ +# The notifying class mixes in the +Observable+ # module, which provides the methods for managing the associated observer # objects. # -# The observers must implement the +update+ method to receive notifications. +# The observers must implement a method called +update+ to receive +# notifications. # # The observable object must: -# * assert that it has +changed+ -# * call +notify_observers+ +# * assert that it has +#changed+ +# * call +#notify_observers+ # -# == Example +# === Example # # The following example demonstrates this nicely. A +Ticker+, when run, -# continually receives the stock +Price+ for its +@symbol+. A +Warner+ is a -# general observer of the price, and two warners are demonstrated, a +WarnLow+ -# and a +WarnHigh+, which print a warning if the price is below or above their -# set limits, respectively. +# continually receives the stock +Price+ for its @symbol. A +Warner+ +# is a general observer of the price, and two warners are demonstrated, a +# +WarnLow+ and a +WarnHigh+, which print a warning if the price is below or +# above their set limits, respectively. # # The +update+ callback allows the warners to run without being explicitly # called. The system is set up with the +Ticker+ and several observers, and the @@ -108,19 +109,20 @@ # Current price: 112 # Current price: 79 # --- Sun Jun 09 00:10:25 CDT 2002: Price below 80: 79 - - -# -# Implements the Observable design pattern as a mixin so that other objects can -# be notified of changes in state. See observer.rb for details and an example. -# module Observable # - # Add +observer+ as an observer on this object. +observer+ will now receive - # notifications. The second optional argument specifies a method to notify - # updates, of which default value is +update+. + # Add +observer+ as an observer on this object. so that it will receive + # notifications. + # + # +observer+:: the object that will be notified of changes. + # +func+:: Symbol naming the method that will be called when this Observable + # has changes. # + # This method must return true for +observer.respond_to?+ and will + # receive *arg when #notify_observers is called, where + # *arg is the value passed to #notify_observers by this + # Observable def add_observer(observer, func=:update) @observer_peers = {} unless defined? @observer_peers unless observer.respond_to? func @@ -130,15 +132,16 @@ module Observable end # - # Delete +observer+ as an observer on this object. It will no longer receive - # notifications. + # Remove +observer+ as an observer on this object so that it will no longer + # receive notifications. # + # +observer+:: An observer of this Observable def delete_observer(observer) @observer_peers.delete observer if defined? @observer_peers end # - # Delete all observers associated with this object. + # Remove all observers associated with this object. # def delete_observers @observer_peers.clear if defined? @observer_peers @@ -159,12 +162,15 @@ module Observable # Set the changed state of this object. Notifications will be sent only if # the changed +state+ is +true+. # + # +state+:: Boolean indicating the changed state of this Observable. + # def changed(state=true) @observer_state = state end # - # Query the changed state of this object. + # Returns true if this object's state has been changed since the last + # #notify_observers call. # def changed? if defined? @observer_state and @observer_state @@ -175,16 +181,19 @@ module Observable end # - # If this object's changed state is +true+, invoke the update method in each - # currently associated observer in turn, passing it the given arguments. The - # changed state is then set to +false+. + # Notify observers of a change in state *if* this object's changed state is + # +true+. + # + # This will invoke the method named in #add_observer, pasing *arg. + # The changed state is then set to +false+. # + # *arg:: Any arguments to pass to the observers. def notify_observers(*arg) if defined? @observer_state and @observer_state if defined? @observer_peers - @observer_peers.each { |k, v| - k.send v, *arg - } + @observer_peers.each do |k, v| + k.send v, *arg + end end @observer_state = false end -- cgit v1.2.3