doc: stop recommending Fiber* stuff

Too much NIH and too fragile.

3 files changed, 21 insertions, 6 deletions

diff --git a/lib/rainbows/fiber/io.rb b/lib/rainbows/fiber/io.rb
index da377d0..3005d96 100644
--- a/lib/rainbows/fiber/io.rb
+++ b/lib/rainbows/fiber/io.rb
@@ -1,13 +1,18 @@
 # -*- encoding: binary -*-
 
-# A Fiber-aware IO class, gives users the illusion of a synchronous
-# interface that yields away from the current Fiber whenever
+# A \Fiber-aware IO class, gives users the illusion of a synchronous
+# interface that yields away from the current \Fiber whenever
 # the underlying descriptor is blocked on reads or write
 #
+# It's not recommended to use any of this in your applications
+# unless you're willing to accept breakage.  Most of this is very
+# difficult-to-use, fragile and we don't have much time to devote to
+# supporting these in the future.
+#
 # This is a stable, legacy interface and should be preserved for all
 # future versions of Rainbows!  However, new apps should use
-# Rainbows::Fiber::IO::Socket or Rainbows::Fiber::IO::Pipe instead.
-
+# Rainbows::Fiber::IO::Socket or Rainbows::Fiber::IO::Pipe instead
+# (or better yet, avoid any of the Rainbows::Fiber* stuff).
 class Rainbows::Fiber::IO
   attr_accessor :to_io
 
diff --git a/lib/rainbows/fiber/io/pipe.rb b/lib/rainbows/fiber/io/pipe.rb
index c7ae508..59114d7 100644
--- a/lib/rainbows/fiber/io/pipe.rb
+++ b/lib/rainbows/fiber/io/pipe.rb
@@ -1,7 +1,12 @@
 # -*- encoding: binary -*-
 # A Fiber-aware Pipe class, gives users the illusion of a synchronous
 # interface that yields away from the current Fiber whenever
-# the underlying descriptor is blocked on reads or write
+# the underlying descriptor is blocked on reads or write.
+#
+# It's not recommended to use any of this in your applications
+# unless you're willing to accept breakage.  Most of this is very
+# difficult-to-use, fragile and we don't have much time to devote to
+# supporting these in the future.
 class Rainbows::Fiber::IO::Pipe < Kgio::Pipe
   include Rainbows::Fiber::IO::Methods
 end
diff --git a/lib/rainbows/fiber/io/socket.rb b/lib/rainbows/fiber/io/socket.rb
index 61c451d..2b4df12 100644
--- a/lib/rainbows/fiber/io/socket.rb
+++ b/lib/rainbows/fiber/io/socket.rb
@@ -1,7 +1,12 @@
 # -*- encoding: binary -*-
 # A Fiber-aware Socket class, gives users the illusion of a synchronous
 # interface that yields away from the current Fiber whenever
-# the underlying descriptor is blocked on reads or write
+# the underlying descriptor is blocked on reads or write.
+#
+# It's not recommended to use any of this in your applications
+# unless you're willing to accept breakage.  Most of this is very
+# difficult-to-use, fragile and we don't have much time to devote to
+# supporting these in the future.
 class Rainbows::Fiber::IO::Socket < Kgio::Socket
   include Rainbows::Fiber::IO::Methods
 end