Doc update

* add missing edge warnings
* readme update
* todo updates

Author: pitr-ch

.yardopts

@@ -8,6 +8,7 @@
 --default-return undocumented
 
 ./lib/**/*.rb
+./lib-edge/**/*.rb
 ./ext/concurrent_ruby_ext/**/*.c
 -
 doc/thread_pools.md

README.md

@@ -3,7 +3,6 @@
 [![Gem Version](https://badge.fury.io/rb/concurrent-ruby.svg)](http://badge.fury.io/rb/concurrent-ruby)
 [![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby)
 [![Build status](https://ci.appveyor.com/api/projects/status/iq8aboyuu3etad4w?svg=true)](https://ci.appveyor.com/project/rubyconcurrency/concurrent-ruby)
-[![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
 [![Gitter chat](https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
 
@@ -52,11 +51,19 @@ We also have a [mailing list](http://groups.google.com/group/concurrent-ruby) an
 #### General-purpose Concurrency Abstractions
 
 * [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's [gen_server](http://www.erlang.org/doc/man/gen_server.html).
-* [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.
-  * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
-* [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.
 * [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
 * [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals.
+* [Promises Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promises.html):
+  Unified implementation of futures and promises which combines features of previous `Future`,
+  `Promise`, `IVar`, `Event`, `dataflow`, `Delay`, and (partially) `TimerTask` into a single framework. It extensively uses the
+  new synchronization layer to make all the features **non-blocking** and **lock-free**, with the exception of obviously blocking
+  operations like `#wait`, `#value`. It also offers better performance.
+
+Deprecated:
+  
+* ~~[Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.~~
+  * ~~[Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.~~
+* ~~[Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.~~
 
 #### Thread-safe Value Objects, Structures, and Collections
 
@@ -115,13 +122,6 @@ These features are under active development and may change frequently. They are
 keep backward compatibility (there may also lack tests and documentation). Semantic versions will
 be obeyed though. Features developed in `concurrent-ruby-edge` are expected to move to `concurrent-ruby` when final.
 
-* [Promises Framework](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promises.html):
-  Unified implementation of futures and promises which combines features of previous `Future`,
-  `Promise`, `IVar`, `Event`, `dataflow`, `Delay`, and `TimerTask` into a single framework. It extensively uses the
-  new synchronization layer to make all the features **non-blocking** and **lock-free**, with the exception of 
-  obviously blocking operations like `#wait`, `#value`. It also offers better performance. 
-  Status: The framework is being finalized so it can be moved to core. It will eventually replace old implementations 
-  it replaces.
 * [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
   Implements the Actor Model, where concurrent actors exchange messages.
   Status: Partial documentation and tests; depends on new future/promise framework; stability is good.

lib-edge/concurrent/channel.rb

@@ -9,6 +9,7 @@
 module Concurrent
 
   # {include:file:doc/channel.md}
+  # @!macro edge_warning
   class Channel
     extend Forwardable
     include Enumerable

lib/concurrent/edge.rb renamed to lib-edge/concurrent/edge.rb

@@ -17,10 +17,14 @@ module Concurrent
   #
   # @!macro [attach] edge_warning
   #   @api Edge
-  #   @note **Edge Feature:** Edge features are under active development and may change frequently. They are expected not to
-  #     keep backward compatibility (there may also lack tests and documentation). Semantic versions will
-  #     be obeyed though. Features developed in `concurrent-ruby-edge` are expected to move
-  #     to `concurrent-ruby` when final.
+  #   @note **Edge Features** are under active development and may change frequently.
+  #
+  #     -   Deprecations are not added before incompatible changes.
+  #     -   Edge version: _major_ is always 0, _minor_ bump means incompatible change,
+  #         _patch_ bump means compatible change.
+  #     -   Edge features may also lack tests and documentation.
+  #     -   Features developed in `concurrent-ruby-edge` are expected to move
+  #         to `concurrent-ruby` when finalised.
   module Edge
   end
 end

lib-edge/concurrent/edge/cancellation.rb

@@ -14,6 +14,7 @@ module Concurrent
   #   end
   #   sleep 0.1
   #   cancellation.cancel # Stop the thread by cancelling
+  # @!macro edge_warning
   class Cancellation < Synchronization::Object
     safe_initialization!
 

lib-edge/concurrent/edge/lock_free_linked_set.rb

@@ -18,6 +18,7 @@ module Edge
     #
     # This algorithm is a variation of the Nonblocking Linked Set found in
     # 'The Art of Multiprocessor Programming' by Herlihy and Shavit.
+    # @!macro edge_warning
     class LockFreeLinkedSet
       include Enumerable
 

lib-edge/concurrent/edge/processing_actor.rb

@@ -135,7 +135,7 @@ def ask(message, answer = Promises.resolvable_future)
       ).chain do |fulfilled, (which, value), (_, reason)|
         # TODO (pitr-ch 20-Jan-2017): we have to know which future was resolved
         # TODO (pitr-ch 20-Jan-2017): make the combinator programmable, so anyone can create what is needed
-        # TODO (pitr-ch 19-Jan-2017): ensure no callbacks are accumulated on @Terminated
+        # FIXME (pitr-ch 19-Jan-2017): ensure no callbacks are accumulated on @Terminated
         if which == :termination
           raise reason.nil? ? format('actor terminated normally before answering with a value: %s', value) : reason
         else

lib-edge/concurrent/edge/promises.rb

@@ -1,8 +1,4 @@
 # TODO try stealing pool, each thread has it's own queue
-# TODO (pitr-ch 18-Dec-2016): doc macro debug method
-# TODO (pitr-ch 18-Dec-2016): add macro noting that debug methods may change api without warning
-
-# FIXME (pitr-ch 23-Feb-2017): documentation has to clearly explain what is an edge method and what is not
 
 require 'concurrent/promises'
 
@@ -122,7 +118,6 @@ def then_push_channel(channel)
           self.then { |value| channel.push value }.flat_future
         end
 
-        # TODO (pitr-ch 26-Dec-2016): does it make sense to have rescue an chain variants as well, check other integrations as well
       end
 
       include NewChannelIntegration

lib-edge/concurrent/edge/throttle.rb

@@ -48,6 +48,7 @@ module Concurrent
   # @!macro throttle.example.throttled_future
   # @!macro throttle.example.throttled_future_chain
   # @!macro throttle.example.throttled_block
+  # @!macro edge_warning
   class Throttle < Synchronization::Object
     # TODO (pitr-ch 21-Dec-2016): consider using sized channel for implementation instead when available
 

lib/concurrent/future.rb

@@ -6,6 +6,8 @@
 
 require 'concurrent/options'
 
+# TODO (pitr-ch 14-Mar-2017): deprecate, Future, Promise, etc.
+
 module Concurrent
 
   # {include:file:doc/future.md}