Improved yardoc macro placement.

Author: jdantonio

lib/concurrent.rb

@@ -49,6 +49,62 @@
 #
 #   @see http://linux.die.net/man/3/clock_gettime Linux clock_gettime(3)
 
+# @!macro [new] copy_options
+#
+#   ## Copy Options
+#
+#   Object references in Ruby are mutable. This can lead to serious
+#   problems when the {#value} of an object is a mutable reference. Which
+#   is always the case unless the value is a `Fixnum`, `Symbol`, or similar
+#   "primative" data type. Each instance can be configured with a few
+#   options that can help protect the program from potentially dangerous
+#   operations. Each of these options can be optionally set when the oject
+#   instance is created:
+#
+#   * `:dup_on_deref` When true the object will call the `#dup` method on
+#     the `value` object every time the `#value` methid is called
+#     (default: false)
+#   * `:freeze_on_deref` When true the object will call the `#freeze`
+#     method on the `value` object every time the `#value` method is called
+#     (default: false)
+#   * `:copy_on_deref` When given a `Proc` object the `Proc` will be run
+#     every time   the `#value` method is called. The `Proc` will be given
+#     the current `value` as its only argument and the result returned by
+#     the block will be the return   value of the `#value` call. When `nil`
+#     this option will be ignored (default: nil)
+#
+#   When multiple deref options are set the order of operations is strictly defined.
+#   The order of deref operations is:
+#   * `:copy_on_deref`
+#   * `:dup_on_deref`
+#   * `:freeze_on_deref`
+#
+#   Because of this ordering there is no need to `#freeze` an object created by a
+#   provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
+#   Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
+#   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
+#   or Haskell) as we are likely to get in Ruby.
+
+# @!macro [attach] deref_options
+#
+#   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
+#     returning the data from {#value}
+#   @option opts [Boolean] :freeze_on_deref (false) Call `#freeze` before
+#     returning the data from {#value}
+#   @option opts [Proc] :copy_on_deref (nil) When calling the {#value}
+#     method, call the given proc passing the internal value as the sole
+#     argument then return the new value returned from the proc.
+
+# @!macro [attach] executor_and_deref_options
+#
+#   @param [Hash] opts the options used to define the behavior at update and deref
+#     and to specify the executor on which to perform actions
+#   @option opts [Executor] :executor when set use the given `Executor` instance.
+#     Three special values are also supported: `:task` returns the global task pool,
+#     `:operation` returns the global operation pool, and `:immediate` returns a new
+#     `ImmediateExecutor` object.
+#   @!macro deref_options
+
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.
 #

lib/concurrent/agent.rb

@@ -93,15 +93,7 @@ class Agent
     #
     # @param [Object] initial the initial value
     #
-    # @!macro [attach] executor_and_deref_options
-    #  
-    #   @param [Hash] opts the options used to define the behavior at update and deref
-    #     and to specify the executor on which to perform actions
-    #   @option opts [Executor] :executor when set use the given `Executor` instance.
-    #     Three special values are also supported: `:task` returns the global task pool,
-    #     `:operation` returns the global operation pool, and `:immediate` returns a new
-    #     `ImmediateExecutor` object.
-    #   @!macro deref_options
+    # @!macro executor_and_deref_options
     def initialize(initial, opts = {})
       @value                = initial
       @rescuers             = []

lib/concurrent/atom.rb

@@ -18,40 +18,7 @@ module Concurrent
   # new value to the result of running the given block if and only if that
   # value validates.
   #
-  # @!macro [attach] copy_options
-  #   ## Copy Options
-  #
-  #   Object references in Ruby are mutable. This can lead to serious
-  #   problems when the {#value} of an object is a mutable reference. Which
-  #   is always the case unless the value is a `Fixnum`, `Symbol`, or similar
-  #   "primative" data type. Each instance can be configured with a few
-  #   options that can help protect the program from potentially dangerous
-  #   operations. Each of these options can be optionally set when the oject
-  #   instance is created: 
-  #
-  #   * `:dup_on_deref` When true the object will call the `#dup` method on
-  #     the `value` object every time the `#value` methid is called
-  #     (default: false)
-  #   * `:freeze_on_deref` When true the object will call the `#freeze`
-  #     method on the `value` object every time the `#value` method is called
-  #     (default: false)
-  #   * `:copy_on_deref` When given a `Proc` object the `Proc` will be run
-  #     every time   the `#value` method is called. The `Proc` will be given
-  #     the current `value` as its only argument and the result returned by
-  #     the block will be the return   value of the `#value` call. When `nil`
-  #     this option will be ignored (default: nil)
-  #  
-  #   When multiple deref options are set the order of operations is strictly defined.
-  #   The order of deref operations is:
-  #   * `:copy_on_deref`
-  #   * `:dup_on_deref`
-  #   * `:freeze_on_deref`
-  #  
-  #   Because of this ordering there is no need to `#freeze` an object created by a
-  #   provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
-  #   Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
-  #   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
-  #   or Haskell) as we are likely to get in Ruby.
+  # @!macro copy_options
   #
   # @see http://clojure.org/atoms Clojure Atoms
   class Atom < Synchronization::Object
@@ -66,14 +33,7 @@ class Atom < Synchronization::Object
     #   intended new value. The validator will return true if the new value
     #   is acceptable else return false (preferrably) or raise an exception.
     #
-    # @!macro [attach] deref_options
-    #   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
-    #     returning the data from {#value}
-    #   @option opts [Boolean] :freeze_on_deref (false) Call `#freeze` before
-    #     returning the data from {#value}
-    #   @option opts [Proc] :copy_on_deref (nil) When calling the {#value}
-    #     method, call the given proc passing the internal value as the sole
-    #     argument then return the new value returned from the proc.
+    # @!macro deref_options
     # 
     # @raise [ArgumentError] if the validator is not a `Proc` (when given)
     def initialize(value, opts = {})