You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2017/09/28 21:46:48 UTC
[2/3] qpid-proton git commit: PROTON-1560: ruby: documentation
cleanup and install
PROTON-1560: ruby: documentation cleanup and install
Remove some premature deprecations, clean up some comments.
Generate and install doc from cmake.
Gem docs can be viewed with the usual tools: ri, yard etc.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/5b3b283f
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/5b3b283f
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/5b3b283f
Branch: refs/heads/master
Commit: 5b3b283f4defc2c3b0676a0a0bcb6a771b00c8f0
Parents: c31ca95
Author: Alan Conway <ac...@redhat.com>
Authored: Thu Sep 28 15:12:54 2017 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Thu Sep 28 16:37:27 2017 -0400
----------------------------------------------------------------------
proton-c/bindings/ruby/CMakeLists.txt | 42 ++++++++++++++++++++
proton-c/bindings/ruby/README.rdoc | 31 +++++----------
proton-c/bindings/ruby/lib/codec/data.rb | 5 +--
proton-c/bindings/ruby/lib/core/connection.rb | 4 --
proton-c/bindings/ruby/lib/core/message.rb | 16 +-------
proton-c/bindings/ruby/lib/core/sender.rb | 2 +-
proton-c/bindings/ruby/lib/core/url.rb | 12 ------
.../ruby/lib/handler/messaging_handler.rb | 2 -
.../bindings/ruby/lib/messenger/messenger.rb | 3 --
proton-c/bindings/ruby/lib/reactor/container.rb | 41 ++++++++-----------
proton-c/bindings/ruby/lib/reactor/urls.rb | 4 +-
proton-c/bindings/ruby/lib/util/engine.rb | 2 +-
12 files changed, 76 insertions(+), 88 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/CMakeLists.txt
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/CMakeLists.txt b/proton-c/bindings/ruby/CMakeLists.txt
index 7ff23ed..eb84a6c 100644
--- a/proton-c/bindings/ruby/CMakeLists.txt
+++ b/proton-c/bindings/ruby/CMakeLists.txt
@@ -38,6 +38,29 @@ set_target_properties(cproton-ruby
OUTPUT_NAME "cproton"
LINK_FLAGS "${CATCH_UNDEFINED}" )
+## Make a gem
+
+file(GLOB_RECURSE RUBY_SRC RELATIVE . *.rb *.rdoc)
+
+find_program(GEM_EXE gem DOC "Program to build and install ruby gem packages")
+mark_as_advanced(GEM_EXE)
+if (GEM_EXE)
+ configure_file(qpid_proton.gemspec.in qpid_proton.gemspec)
+ add_custom_command(
+ OUTPUT ${bin}/qpid_proton-${PN_VERSION}.gem
+ DEPENDS ${RUBY_SRC} ${src}/LICENSE ${src}/TODO ${src}/ChangeLog ${bin}/rubyRUBY_wrap.c
+ COMMAND ${CMAKE_COMMAND} -E copy_directory ${src}/lib ${bin}/lib
+ COMMAND ${CMAKE_COMMAND} -E copy_directory ${src}/ext ${bin}/ext
+ COMMAND ${CMAKE_COMMAND} -E copy ${src}/LICENSE ${src}/TODO ${src}/ChangeLog ${bin}
+ COMMAND ${CMAKE_COMMAND} -E copy ${bin}/rubyRUBY_wrap.c ${bin}/ext/cproton/cproton.c
+ COMMAND ${GEM_EXE} build qpid_proton.gemspec
+ WORKING_DIRECTORY ${bin})
+
+ add_custom_target(ruby-gem ALL DEPENDS ${bin}/qpid_proton-${PN_VERSION}.gem )
+endif ()
+
+## CMake-based install
+
if (CHECK_SYSINSTALL_RUBY)
execute_process(COMMAND ${RUBY_EXECUTABLE}
-r rbconfig -e "print RbConfig::CONFIG['vendorarchdir'] || ''"
@@ -95,3 +118,22 @@ else()
# No minitest
message(WARNING "ruby tests will not run, minitest is not installed")
endif()
+
+## Documentation
+
+find_program(YARD_EXE "yard")
+if (YARD_EXE)
+ add_custom_command(
+ OUTPUT ${bin}/doc
+ WORKING_DIRECTORY ${src}
+ COMMAND ${YARD_EXE} -q -o ${bin}/doc -b ${bin}/.yardoc --no-private -r README.rdoc
+ DEPENDS ${RUBY_SRC}
+ )
+ add_custom_target(docs-ruby DEPENDS ${bin}/doc)
+ add_dependencies (docs docs-ruby)
+ install(DIRECTORY "${bin}/doc/"
+ DESTINATION "${PROTON_SHARE}/docs/api-ruby"
+ COMPONENT documentation
+ OPTIONAL)
+ set_directory_properties(PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES doc)
+endif()
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/README.rdoc
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/README.rdoc b/proton-c/bindings/ruby/README.rdoc
index 1663957..0382231 100644
--- a/proton-c/bindings/ruby/README.rdoc
+++ b/proton-c/bindings/ruby/README.rdoc
@@ -1,31 +1,20 @@
-Qpid Proton Ruby Language Bindings
-==================================
+= Qpid Proton Ruby Language Bindings
-The Ruby code contained here provides Ruby language bindings for working
-with the Proton messaging framework.
+This is a Ruby language binding for the Qpid proton AMQP messaging library.
+You can build clients and servers using this library.
-Creating The Bindings
-=====================
-To generate the bindings, you will need to have the Proton messaging
-libraries installed. You will also need to have Swig [1].
+== Installing
-To generate the bindings, simply type:
+If you have the complete proton sources, you can build and install locally with:
- gem build qpid_proton.gemspec
+ cmake -DBUILD_ONLY=ruby && make install
-This will generate the Ruby wrapper for the C libraries and bundle them,
-along with the public APIs, into a gemfile. You can then install that
-gem file using:
+The cmake build also produces a Ruby Gem file at:
- gem install qpid_proton-##.gem
+ ${CMAKE_BUILD_DIR}/proton-c/bindings/ruby/qpid_proton-${PN_VERSION}.gem
-where ## is the release version.
+You can install the gem with `gem install` as usual, but note that the proton-C
+library must be before installing the gem.
-[1] http://www.swig.org/
-
-KNOWN ISSUES
-============
-
- * Setting a pn_atom_t of type String to a nil returns an empty string.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/codec/data.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/codec/data.rb b/proton-c/bindings/ruby/lib/codec/data.rb
index 01799fd..afd4e31 100644
--- a/proton-c/bindings/ruby/lib/codec/data.rb
+++ b/proton-c/bindings/ruby/lib/codec/data.rb
@@ -172,10 +172,7 @@ module Qpid::Proton::Codec
return (dtype == -1) ? nil : dtype
end
- # Return the type object for the current node
- #
- # @param [Integer] The object type.
- #
+ # @return [Integer] The type object for the current node.
# @see #type_code
#
def type
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/core/connection.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/connection.rb b/proton-c/bindings/ruby/lib/core/connection.rb
index 949ff2a..784b193 100644
--- a/proton-c/bindings/ruby/lib/core/connection.rb
+++ b/proton-c/bindings/ruby/lib/core/connection.rb
@@ -38,10 +38,6 @@ module Qpid::Proton
# @!attribute user
# The user name for authentication.
#
- # A client sets authentication data with the :user and :password options
- # to {Container#connect}. On a server this returns the authenticated name
- # from the client. It makes no sense to set this on the server side.
- #
# @return [String] the user name
proton_accessor :user
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/core/message.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/message.rb b/proton-c/bindings/ruby/lib/core/message.rb
index 81bbadb..f31ce29 100644
--- a/proton-c/bindings/ruby/lib/core/message.rb
+++ b/proton-c/bindings/ruby/lib/core/message.rb
@@ -407,24 +407,12 @@ module Qpid::Proton
Cproton.pn_message_get_content_type(@impl)
end
- # Sets the message content.
- #
- # *WARNING:* This method has been deprecated. Please use #body= instead to
- # set the content of a message.
- #
- # ==== Options
- #
- # * content - the content
- #
+ # @deprecated use {#body=}
def content=(content)
Cproton.pn_message_load(@impl, content)
end
- # Returns the message content.
- #
- # *WARNING:* This method has been deprecated. Please use #body instead to
- # retrieve the content of a message.
- #
+ # @deprecated use {#body}
def content
size = 16
loop do
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/core/sender.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/sender.rb b/proton-c/bindings/ruby/lib/core/sender.rb
index a63ff9f..deeb0c5 100644
--- a/proton-c/bindings/ruby/lib/core/sender.rb
+++ b/proton-c/bindings/ruby/lib/core/sender.rb
@@ -58,7 +58,7 @@ module Qpid::Proton
#
# @param bytes [Array] The bytes to send.
#
- # @return n [Integer] The number of bytes sent.
+ # @return [Integer] The number of bytes sent.
#
def stream(bytes)
Cproton.pn_link_send(@impl, bytes)
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/core/url.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/url.rb b/proton-c/bindings/ruby/lib/core/url.rb
index 195567f..9034487 100644
--- a/proton-c/bindings/ruby/lib/core/url.rb
+++ b/proton-c/bindings/ruby/lib/core/url.rb
@@ -66,11 +66,6 @@ module Qpid::Proton
"#{@scheme}://#{@username.nil? ? '' : @username}#{@password.nil? ? '' : '@' + @password + ':'}#{@host}:#{@port}/#{@path}"
end
- # Return self
- def to_url()
- self
- end
-
private
def defaults
@@ -80,10 +75,3 @@ module Qpid::Proton
end
end
end
-
-class String
- # Convert this string to a URL
- def to_url()
- return Qpid::Proton::URL.new(self)
- end
-end
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/handler/messaging_handler.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/handler/messaging_handler.rb b/proton-c/bindings/ruby/lib/handler/messaging_handler.rb
index 3278452..d97fe3d 100644
--- a/proton-c/bindings/ruby/lib/handler/messaging_handler.rb
+++ b/proton-c/bindings/ruby/lib/handler/messaging_handler.rb
@@ -21,8 +21,6 @@ module Qpid::Proton::Handler
# A general purpose handler that simplifies processing events.
#
- # @example
- #
class MessagingHandler < Qpid::Proton::BaseHandler
attr_reader :handlers
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/messenger/messenger.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/messenger/messenger.rb b/proton-c/bindings/ruby/lib/messenger/messenger.rb
index ecb5d57..8c4714a 100644
--- a/proton-c/bindings/ruby/lib/messenger/messenger.rb
+++ b/proton-c/bindings/ruby/lib/messenger/messenger.rb
@@ -18,9 +18,6 @@
#
module Qpid::Proton::Messenger
- warn "[DEPRECATION] `Qpid::Proton::Messenger` is deprecated, use `Qpid::Proton::Container`"
-
- # @deprecated Please use {Qpid::Proton::Container} instead.
#
# The +Messenger+ class defines a high level interface for
# sending and receiving Messages. Every Messenger contains
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/reactor/container.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/reactor/container.rb b/proton-c/bindings/ruby/lib/reactor/container.rb
index aa1b303..4623d7a 100644
--- a/proton-c/bindings/ruby/lib/reactor/container.rb
+++ b/proton-c/bindings/ruby/lib/reactor/container.rb
@@ -43,9 +43,6 @@ module Qpid::Proton::Reactor
# This is an extension to the Reactor classthat adds convenience methods
# for creating instances of Qpid::Proton::Connection, Qpid::Proton::Sender
# and Qpid::Proton::Receiver.
- #
- # @example
- #
class Container < Reactor
include Qpid::Proton::Util::Reactor
@@ -74,31 +71,27 @@ module Qpid::Proton::Reactor
end
end
- # TODO aconway 2017-08-17: fill out options
-
- # Connects to a remote AMQP endpoint and sends an AMQP "open" frame.
+ # Initiate an AMQP connection.
#
- # @param url [#to_url] Connect to URL host:port.
- # If URL has user:password use them for authentication.
+ # @param url [String] Connect to URL host:port, using user:password@ if present
+ # @param opts [Hash] Named options
+ # For backwards compatibility, can be called with a single parameter opts.
#
+ # @option opts [String] :url Connect to URL host:port using user:password@ if present.
# @option opts [String] :user user name for authentication if not given by URL
# @option opts [String] :password password for authentication if not given by URL
- #
- # @option opts [Numeric] :idle_timeout seconds before closing an idle connection
- #
+ # @option opts [Numeric] :idle_timeout seconds before closing an idle connection,
+ # can be a fractional value.
# @option opts [Boolean] :sasl_enabled Enable or disable SASL.
- #
# @option opts [Boolean] :sasl_allow_insecure_mechs Allow mechanisms that disclose clear text
# passwords, even over an insecure connection. By default, such mechanisms are only allowed
# when SSL is enabled.
- #
# @option opts [String] :sasl_allowed_mechs the allowed SASL mechanisms for use on the connection.
#
- # @param url [Hash] *deprecated* if url is a Hash and opts is unspecified, treat it as opts.
- # @option opts [#to_url] :url *deprecated* use the url parameter
- # @option opts [Enumerable<#to_url>] :urls *deprecated* use the url parameter
- # @option opts [#to_url] :address *deprecated* use the url parameter
- # @option opts [#to_url] :heartbeat *deprecated* alias for :idle_timeout, but in milliseconds
+ # @option opts [String] :address *deprecated* use the :url option
+ # @option opts [Numeric] :heartbeat milliseconds before closing an idle connection.
+ # *deprecated* use :idle_timeout => heartbeat/1000
+ #
# @return [Connection] the new connection
#
def connect(url, opts = {})
@@ -135,12 +128,12 @@ module Qpid::Proton::Reactor
#
# @param context [String, URL] The context.
# @param opts [Hash] Additional options.
- # @param opts [String, Qpid::Proton::URL] The target address.
- # @param opts [String] :source The source address.
- # @param opts [Boolean] :dynamic
- # @param opts [Object] :handler
- # @param opts [Object] :tag_generator The tag generator.
- # @param opts [Hash] :options Addtional link options
+ # @option opts [String, Qpid::Proton::URL] The target address.
+ # @option opts [String] :source The source address.
+ # @option opts [Boolean] :dynamic
+ # @option opts [Object] :handler
+ # @option opts [Object] :tag_generator The tag generator.
+ # @option opts [Hash] :options Addtional link options
#
# @return [Sender] The sender.
#
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/reactor/urls.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/reactor/urls.rb b/proton-c/bindings/ruby/lib/reactor/urls.rb
index 44fd956..92cab81 100644
--- a/proton-c/bindings/ruby/lib/reactor/urls.rb
+++ b/proton-c/bindings/ruby/lib/reactor/urls.rb
@@ -24,9 +24,9 @@ module Qpid::Proton::Reactor
def initialize(values)
@values = values
if @values.is_a? Enumerable
- @values = @values.map { |u| u.to_url }
+ @values = @values.map { |u| Qpid::Proton::URL.new(u) }
else
- @values = [values.to_url]
+ @values = [Qpid::Proton::URL.new(values)]
end
@iter = @values.each
end
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/5b3b283f/proton-c/bindings/ruby/lib/util/engine.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/util/engine.rb b/proton-c/bindings/ruby/lib/util/engine.rb
index 53aa672..e34faaa 100644
--- a/proton-c/bindings/ruby/lib/util/engine.rb
+++ b/proton-c/bindings/ruby/lib/util/engine.rb
@@ -25,7 +25,7 @@ module Qpid::Proton::Util
# Convenience method to receive messages from a delivery.
#
# @param delivery [Qpid::Proton::Delivery] The delivery.
- # @param message [Qpid::Proton::Message] The message to use.
+ # @param msg [Qpid::Proton::Message] The message to use.
#
# @return [Qpid::Proton::Message] the message
#
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org