Improved some Ruby inline documentation

Dawn9988 · Jul 12, 2016 · 580a64a · 580a64a
1 parent 76c9296
commit 580a64a
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 16 deletions.
diff --git a/src/ruby/lib/grpc/generic/bidi_call.rb b/src/ruby/lib/grpc/generic/bidi_call.rb
@@ -76,7 +76,7 @@ def initialize(call, marshal, unmarshal, metadata_received: false)
     # block that can be invoked with each response.
     #
     # @param requests the Enumerable of requests to send
-    # @op_notifier a Notifier used to signal completion
+    # @param op_notifier a Notifier used to signal completion
     # @return an Enumerator of requests to yield
     def run_on_client(requests, op_notifier, &blk)
       @op_notifier = op_notifier

diff --git a/src/ruby/lib/grpc/generic/client_stub.rb b/src/ruby/lib/grpc/generic/client_stub.rb
@@ -34,7 +34,8 @@
 module GRPC
   # rubocop:disable Metrics/ParameterLists
 
-  # ClientStub represents an endpoint used to send requests to GRPC servers.
+  # ClientStub represents a client connection to a gRPC server, and can be used
+  # to send requests.
   class ClientStub
     include Core::StatusCodes
     include Core::TimeConsts
@@ -75,8 +76,9 @@ def self.setup_channel(alt_chan, host, creds, channel_args = {})
     # my_stub = ClientStub.new(example.host.com:50505,
     #                          :this_channel_is_insecure)
     #
-    # Any arbitrary keyword arguments are treated as channel arguments used to
-    # configure the RPC connection to the host.
+    # If a channel_override argument is passed, it will be used as the
+    # underlying channel. Otherwise, the channel_args argument will be used
+    # to construct a new underlying channel.
     #
     # There are some specific keyword args that are not used to configure the
     # channel:
@@ -91,10 +93,17 @@ def self.setup_channel(alt_chan, host, creds, channel_args = {})
     #
     # @param host [String] the host the stub connects to
     # @param creds [Core::ChannelCredentials|Symbol] the channel credentials, or
-    #     :this_channel_is_insecure
+    #     :this_channel_is_insecure, which explicitly indicates that the client
+    #     should be created with an insecure connection. Note: this argument is
+    #     ignored if the channel_override argument is provided.
     # @param channel_override [Core::Channel] a pre-created channel
     # @param timeout [Number] the default timeout to use in requests
-    # @param channel_args [Hash] the channel arguments
+    # @param propagate_mask [Number] A bitwise combination of flags in
+    #     GRPC::Core::PropagateMasks. Indicates how data should be propagated
+    #     from parent server calls to child client calls if this client is being
+    #     used within a gRPC server.
+    # @param channel_args [Hash] the channel arguments. Note: this argument is
+    #     ignored if the channel_override argument is provided.
     def initialize(host, creds,
                    channel_override: nil,
                    timeout: nil,
@@ -389,11 +398,11 @@ def server_streamer(method, req, marshal, unmarshal,
     # @param marshal [Function] f(obj)->string that marshals requests
     # @param unmarshal [Function] f(string)->obj that unmarshals responses
     # @param deadline [Time] (optional) the time the request should complete
+    # @param return_op [true|false] return an Operation if true
     # @param parent [Core::Call] a prior call whose reserved metadata
     #   will be propagated by this one.
     # @param credentials [Core::CallCredentials] credentials to use when making
     #   the call
-    # @param return_op [true|false] return an Operation if true
     # @param metadata [Hash] metadata to be sent to the server
     # @param blk [Block] when provided, is executed for each response
     # @return [Enumerator|nil|Operation] as discussed above
@@ -430,7 +439,8 @@ def bidi_streamer(method, requests, marshal, unmarshal,
     # @param unmarshal [Function] f(string)->obj that unmarshals responses
     # @param parent [Grpc::Call] a parent call, available when calls are
     #   made from server
-    # @param timeout [TimeConst]
+    # @param credentials [Core::CallCredentials] credentials to use when making
+    #   the call
     def new_active_call(method, marshal, unmarshal,
                         deadline: nil,
                         parent: nil,

diff --git a/src/ruby/lib/grpc/generic/rpc_server.rb b/src/ruby/lib/grpc/generic/rpc_server.rb
@@ -172,22 +172,18 @@ def self.setup_connect_md_proc(a_proc)
     # The RPC server is configured using keyword arguments.
     #
     # There are some specific keyword args used to configure the RpcServer
-    # instance, however other arbitrary are allowed and when present are used
-    # to configure the listeninng connection set up by the RpcServer.
-    #
-    # * poll_period: when present, the server polls for new events with this
-    # period
+    # instance.
     #
     # * pool_size: the size of the thread pool the server uses to run its
     # threads
     #
-    # * creds: [GRPC::Core::ServerCredentials]
-    # the credentials used to secure the server
-    #
     # * max_waiting_requests: the maximum number of requests that are not
     # being handled to allow. When this limit is exceeded, the server responds
     # with not available to new requests
     #
+    # * poll_period: when present, the server polls for new events with this
+    # period
+    #
     # * connect_md_proc:
     # when non-nil is a proc for determining metadata to to send back the client
     # on receiving an invocation req.  The proc signature is: