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 <acon...@redhat.com> Authored: Thu Sep 28 15:12:54 2017 -0400 Committer: Alan Conway <acon...@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-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org