Merge pull request #172 from tbetbetbe/grpc_ruby_cleanup_readme_remove_internal_references

Grpc ruby cleanup readme remove internal references

src/ruby/README.md

@@ -1,64 +1,63 @@
-Ruby for GRPC
-=============
+gRPC Ruby
+=========
 
-LAYOUT
-------
+A Ruby implementation of gRPC, Google's RPC library.
 
-Directory structure is the recommended layout for [ruby extensions](http://guides.rubygems.org/gems-with-extensions/)
 
- * ext: the extension code
- * lib: the entrypoint grpc ruby library to be used in a 'require' statement
- * test: tests
+INSTALLATION PREREQUISITES
+--------------------------
 
+This requires Ruby 2.x, as the rpc api surface uses keyword args.
 
-DEPENDENCIES
-------------
 
+INSTALLING
+----------
 
-* Extension
+- Install the gRPC core library
+TODO: describe this, once the core distribution mechanism is defined.
 
-The extension can be built and tested using
-[rake](https://rubygems.org/gems/rake).  However, the rake-extensiontask rule
-is not supported on older versions of rubygems, and the necessary version of
-rubygems.
+$ gem install grpc
 
-This is resolved by using [RVM](https://rvm.io/) instead; install a single-user
-ruby environment, and develop on the latest stable version of ruby (2.1.5).
 
+Installing from source
+----------------------
 
-INSTALLATION PREREQUISITES
---------------------------
-
-Install RVM
+- Build or Install the gRPC core
+E.g, from the root of the grpc [git repo](https://github.com/google/grpc)
+$ cd ../..
+$ make && sudo make install
 
+- Install Ruby 2.x. Consider doing this with [RVM](http://rvm.io), it's a nice way of controlling
+  the exact ruby version that's used.
 $ command curl -sSL https://rvm.io/mpapis.asc | gpg --import -
 $ \curl -sSL https://get.rvm.io | bash -s stable --ruby
 $
 $ # follow the instructions to ensure that your're using the latest stable version of Ruby
 $ # and that the rvm command is installed
-$
-$ gem install bundler  # install bundler, the standard ruby package manager
 
-HACKING
--------
+- Install [bundler](http://bundler.io/)
+$ gem install bundler
 
-The extension can be built and tested using the Rakefile.
+- Finally, install grpc ruby locally.
+$ cd <install_dir>
+$ bundle install
+$ rake  # compiles the extension, runs the unit tests, see rake -T for other options
 
-$ # create a workspace
-$ git5 start <your-git5-branch> net/grpc
-$
-$ # build the C library and install it in $HOME/grpc_dev
-$ <google3>/net/grpc/c/build_gyp/build_grpc_dev.sh
-$
-$ # build the ruby extension and test it.
-$ cd google3_dir/net/grpc/ruby
-$ rake
 
-Finally, install grpc ruby locally.
+CONTENTS
+--------
 
-$ cd <this_dir>
-$
-$ # update the Gemfile, modify the line beginning # gem 'beefcake' to refer to
-$ # the patched beefcake dir
-$
-$ bundle install
+Directory structure is the layout for [ruby extensions](http://guides.rubygems.org/gems-with-extensions/)
+
+ * ext: the extension code
+ * lib: the entrypoint grpc ruby library to be used in a 'require' statement
+ * spec: tests
+ * bin: example gRPC clients and servers, e.g,
+```ruby
+# client
+stub = Math::Math::Stub.new('my.test.math.server.com:8080')
+req = Math::DivArgs.new(dividend: 7, divisor: 3)
+logger.info("div(7/3): req=#{req.inspect}")
+resp = stub.div(req, INFINITE_FUTURE)
+logger.info("Answer: #{resp.inspect}")
+```

src/ruby/bin/interop/README.md

@@ -1,11 +1,8 @@
 Interop test protos
 ===================
 
-These were generated by a patched version of beefcake and a patched version of
-protoc.
+These ruby classes were generated with protoc v3, using grpc's ruby compiler
+plugin.
 
-- set up and access of the patched versions is described in ../../README.md
-
-The actual test proto is found in Google3 at
-
-- third_party/stubby/testing/proto/test.proto
+- As of 2015/01 protoc v3 is available in the
+[google-protobuf](https://github.com/google/protobuf) repo

src/ruby/bin/interop/interop_server.rb

@@ -145,8 +145,8 @@ class TestTarget < Grpc::Testing::TestService::Service
   end
 
   def half_duplex_call(reqs)
-    # TODO(temiola): clarify the behaviour of the half_duplex_call, it's not
-    # currently used in any tests
+    # TODO: update with unique behaviour of the half_duplex_call if that's
+    # ever required by any of the tests.
     full_duplex_call(reqs)
   end
 end

src/ruby/ext/grpc/extconf.rb

@@ -68,13 +68,9 @@ $CFLAGS << ' -Wno-return-type '
 $CFLAGS << ' -Wall '
 $CFLAGS << ' -pedantic '
 
-$LDFLAGS << ' -lgrpc -lgpr'
-
-# crash('need grpc lib') unless have_library('grpc', 'grpc_channel_destroy')
-#
-# TODO(temiola): figure out why this stopped working, but the so is built OK
-# and the tests pass
+$LDFLAGS << ' -lgrpc -lgpr -ldl'
 
+crash('need grpc lib') unless have_library('grpc', 'grpc_channel_destroy')
 have_library('grpc', 'grpc_channel_destroy')
 crash('need gpr lib') unless have_library('gpr', 'gpr_now')
 create_makefile('grpc/grpc')

src/ruby/ext/grpc/rb_completion_queue.c

@@ -75,7 +75,7 @@ static void grpc_rb_completion_queue_shutdown_drain(grpc_completion_queue *cq) {
   grpc_completion_queue_shutdown(cq);
   next_call.cq = cq;
   next_call.event = NULL;
-  /* TODO(temiola): the timeout should be a module level constant that defaults
+  /* TODO: the timeout should be a module level constant that defaults
    * to gpr_inf_future.
    *
    * - at the moment this does not work, it stalls.  Using a small timeout like

src/ruby/grpc.gemspec

@@ -5,11 +5,11 @@ require 'grpc/version'
 Gem::Specification.new do |s|
   s.name          = 'grpc'
   s.version       = Google::RPC::VERSION
-  s.authors       = ['One Platform Team']
-  s.email         = 'stubby-team@google.com'
-  s.homepage      = 'http://go/grpc'
+  s.authors       = ['gRPC Authors']
+  s.email         = 'tbetbetbe@gmail.com'
+  s.homepage      = 'https://github.com/google/grpc/tree/master/src/ruby'
   s.summary       = 'Google RPC system in Ruby'
-  s.description   = 'Send RPCs from Ruby'
+  s.description   = 'Send RPCs from Ruby using Google's RPC system'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- spec/*`.split("\n")

src/ruby/lib/grpc/beefcake.rb

@@ -1,57 +0,0 @@
-# Copyright 2014, Google Inc.
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are
-# met:
-#
-#     * Redistributions of source code must retain the above copyright
-# notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above
-# copyright notice, this list of conditions and the following disclaimer
-# in the documentation and/or other materials provided with the
-# distribution.
-#     * Neither the name of Google Inc. nor the names of its
-# contributors may be used to endorse or promote products derived from
-# this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-require 'beefcake'
-
-module Beefcake
-  # Re-open the beefcake message module to add a static encode
-  #
-  # This is a temporary measure while beefcake is used as the default proto
-  # library for developing grpc ruby.  Once that changes to the official proto
-  # library this can be removed.  It's necessary to allow the update the service
-  # module to assume a static encode method.
-  # TODO(temiola): remove this.
-  module Message
-    # additional mixin module that adds static encode method when include
-    module StaticEncode
-      # encodes o with its instance#encode method
-      def encode(o)
-        o.encode
-      end
-    end
-
-    # extend self.included in Beefcake::Message to include StaticEncode
-    def self.included(o)
-      o.extend StaticEncode
-      o.extend Dsl
-      o.extend Decode
-      o.send(:include, Encode)
-    end
-  end
-end

src/ruby/lib/grpc/generic/bidi_call.rb

@@ -142,7 +142,7 @@ module Google
       # during bidi-streaming, read the requests to send from a separate thread
       # read so that read_loop does not block waiting for requests to read.
       def start_write_loop(requests, is_client: true)
-        Thread.new do  # TODO(temiola) run on a thread pool
+        Thread.new do  # TODO: run on a thread pool
           write_tag = Object.new
           begin
             count = 0

src/ruby/lib/grpc/generic/rpc_server.rb

@@ -233,10 +233,6 @@ module Google
       end
 
       def new_active_server_call(call, new_server_rpc)
-        # TODO(temiola): perhaps reuse the main server completion queue here,
-        # but for now, create a new completion queue per call, pending best
-        # practice usage advice from the c core.
-
         # Accept the call.  This is necessary even if a status is to be sent
         # back immediately
         finished_tag = Object.new
@@ -340,7 +336,7 @@ module Google
           @workers.size.times { schedule { throw :exit } }
           @stopped = true
 
-          # TODO(temiola): allow configuration of the keepalive period
+          # TODO: allow configuration of the keepalive period
           keep_alive = 5
           @stop_mutex.synchronize do
             @stop_cond.wait(@stop_mutex, keep_alive) if @workers.size > 0

src/ruby/lib/grpc/logconfig.rb

@@ -34,7 +34,7 @@ include Logging.globally  # logger is accessible everywhere
 Logging.logger.root.appenders = Logging.appenders.stdout
 Logging.logger.root.level = :info
 
-# TODO(temiola): provide command-line configuration for logging
+# TODO: provide command-line configuration for logging
 Logging.logger['Google::RPC'].level = :debug
 Logging.logger['Google::RPC::ActiveCall'].level = :info
 Logging.logger['Google::RPC::BidiCall'].level = :info

src/ruby/spec/client_server_spec.rb

@@ -294,7 +294,7 @@ shared_examples 'GRPC metadata delivery works OK' do
       expect_next_event_on(@server_queue, WRITE_ACCEPTED, @server_tag)
 
       # there is the HTTP status metadata, though there should not be any
-      # TODO(temiola): update this with the bug number to be resolved
+      # TODO: update this with the bug number to be resolved
       ev = expect_next_event_on(@client_queue, CLIENT_METADATA_READ, @tag)
       expect(ev.result).to eq(':status' => '200')
     end

src/ruby/spec/testdata/README

@@ -1,4 +1 @@
 These are test keys *NOT* to be used in production.
-http://go/keyhunt requires this README
-
-CONFIRMEDTESTKEY