Author: aconway
Date: Tue Oct 30 16:36:27 2007
New Revision: 590512
URL: http://svn.apache.org/viewvc?rev=590512&view=rev
Log:
Generate doxygen comments for Session_0_10 using AMQP <doc> elements.
Modified:
incubator/qpid/trunk/qpid/cpp/rubygen/amqpgen.rb
incubator/qpid/trunk/qpid/cpp/rubygen/cppgen.rb
incubator/qpid/trunk/qpid/cpp/rubygen/templates/Session.rb
Modified: incubator/qpid/trunk/qpid/cpp/rubygen/amqpgen.rb
URL:
http://svn.apache.org/viewvc/incubator/qpid/trunk/qpid/cpp/rubygen/amqpgen.rb?rev=590512&r1=590511&r2=590512&view=diff
==============================================================================
--- incubator/qpid/trunk/qpid/cpp/rubygen/amqpgen.rb (original)
+++ incubator/qpid/trunk/qpid/cpp/rubygen/amqpgen.rb Tue Oct 30 16:36:27 2007
@@ -89,7 +89,7 @@
class AmqpElement
def wrap(xml)
- return nil if ["doc","assert","rule"].include? xml.name
+ return nil if ["assert","rule"].include? xml.name
eval("Amqp"+xml.name.caps).new(xml, self) or raise "nil wrapper"
end
@@ -103,7 +103,7 @@
@[EMAIL PROTECTED]
end
- attr_reader :parent, :xml, :children
+ attr_reader :parent, :xml, :children, :doc
amqp_attr_reader :name, :label
# List of children of type elname, or all children if elname
@@ -128,6 +128,11 @@
end
AmqpResponse = AmqpElement
+
+class AmqpDoc < AmqpElement
+ def initialize(xml,parent) super; end
+ def text() @xml.text end
+end
class AmqpDomain < AmqpElement
def initialize(xml, parent) super; end
Modified: incubator/qpid/trunk/qpid/cpp/rubygen/cppgen.rb
URL:
http://svn.apache.org/viewvc/incubator/qpid/trunk/qpid/cpp/rubygen/cppgen.rb?rev=590512&r1=590511&r2=590512&view=diff
==============================================================================
--- incubator/qpid/trunk/qpid/cpp/rubygen/cppgen.rb (original)
+++ incubator/qpid/trunk/qpid/cpp/rubygen/cppgen.rb Tue Oct 30 16:36:27 2007
@@ -235,6 +235,12 @@
names=full_cname.split("::")
return names[0..-2].join('::'), names[-1], names.join("/")
end
+
+ def doxygen_comment(&block)
+ genl "/**"
+ prefix(" * ",&block)
+ genl " */"
+ end
end
# Fully-qualified class name
Modified: incubator/qpid/trunk/qpid/cpp/rubygen/templates/Session.rb
URL:
http://svn.apache.org/viewvc/incubator/qpid/trunk/qpid/cpp/rubygen/templates/Session.rb?rev=590512&r1=590511&r2=590512&view=diff
==============================================================================
--- incubator/qpid/trunk/qpid/cpp/rubygen/templates/Session.rb (original)
+++ incubator/qpid/trunk/qpid/cpp/rubygen/templates/Session.rb Tue Oct 30
16:36:27 2007
@@ -11,22 +11,38 @@
excludes.include? m.parent.name
}
end
+
+ def doxygen(m)
+ doxygen_comment {
+ genl m.doc
+ genl
+ m.fields_c.each { |f|
+ genl "@param #{f.cppname}"
+ genl f.doc if f.doc
+ genl
+ }
+ }
+ end
end
class ContentField # For extra content parameters
def cppname() "content" end
def signature() "const MethodContent& content" end
+ def sig_default() signature+"="+"DefaultContent(std::string())" end
def unpack() "p[arg::content|DefaultContent(std::string())]"; end
+ def doc() "Message content"; end
end
class AmqpField
def unpack() "p[arg::#{cppname}|#{cpptype.default_value}]"; end
+ def sig_default() signature+"="+cpptype.default_value; end
end
class AmqpMethod
def fields_c() content ? fields+[ContentField.new] : fields end
def param_names_c() fields_c.map { |f| f.cppname} end
def signature_c() fields_c.map { |f| f.signature }; end
+ def sig_c_default() fields_c.map { |f| f.sig_default }; end
def argpack_name() "#{parent.cppname}#{name.caps}Parameters"; end
def argpack_type()
"boost::parameter::parameters<" +
@@ -73,24 +89,42 @@
genl "using framing::SequenceNumberSet;"
genl "using framing::Uuid;"
genl
- namespace("no_keyword") {
+ namespace("no_keyword") {
+ doxygen_comment {
+ genl "AMQP [EMAIL PROTECTED] session API."
+ genl @amqp.class_("session").doc
+ }
cpp_class(@classname) {
public
gen <<EOS
[EMAIL PROTECTED]();
+
+/** Get the next message frame-set from the session. */
framing::FrameSet::shared_ptr get() { return impl->get(); }
+
+/** Get the session ID */
Uuid getId() const { return impl->getId(); }
-void setSynchronous(bool sync) { impl->setSync(sync); }
+
+/** @param sync if true all session methods block till a response arrives. */
+void setSynchronous(bool sync) { impl->setSync(sync); }
+
+/** Suspend the session, can be resumed on a different connection.
+ * @see Connection::resume()
+ */
void suspend();
+
+/** Close the session */
void close();
+
Execution& execution() { return impl->getExecution(); }
typedef framing::TransferContent DefaultContent;
EOS
- session_methods.each { |m|
- genl
- args=m.signature_c.join(", ")
- genl "#{m.return_type} #{m.session_function}(#{args});"
+ session_methods.each { |m|
+ genl
+ doxygen(m)
+ args=m.sig_c_default.join(", ")
+ genl "#{m.return_type} #{m.session_function}(#{args});"
}
genl
protected
@@ -103,9 +137,9 @@
}}}}
cpp_file(@file) {
- include @classname
- include "qpid/framing/all_method_bodies.h"
- namespace(@namespace) {
+ include @classname
+ include "qpid/framing/all_method_bodies.h"
+ namespace(@namespace) {
gen <<EOS
using namespace framing;
[EMAIL PROTECTED]::[EMAIL PROTECTED]() {}
@@ -166,6 +200,30 @@
genl "BOOST_PARAMETER_KEYWORD(keyword_tags, #{k})"
}}
genl
+ # Doxygen comment.
+ doxygen_comment {
+ genl "AMQP [EMAIL PROTECTED] session API with keyword arguments."
+ genl <<EOS
+This class provides the same set of functions as [EMAIL PROTECTED], but also
+allows parameters be passed using keywords. The keyword is the
+parameter name in the namespace "arg".
+
+For example given the normal function "foo(int x=0, int y=0, int z=0)"
+you could call it in either of the following ways:
+
[EMAIL PROTECTED]
+session.foo(1,2,3); // Normal no keywords
+session.foo(arg::z=3, arg::x=1); // Keywords and a default
[EMAIL PROTECTED]
+
+The keyword functions are easy to use but their declarations are hard
+to read. You may find it easier to read the documentation for [EMAIL PROTECTED]
+which provides the same set of functions using normal non-keyword
+declarations.
+
+EOS
+ }
+ # Session class.
cpp_class(@classname,"public [EMAIL PROTECTED]") {
private
genl "[EMAIL PROTECTED](shared_ptr<SessionCore> core) : #{
@base}(core) {}"
@@ -174,7 +232,7 @@
public
genl "[EMAIL PROTECTED]() {}"
keyword_methods.each { |m| gen_keyword_decl(m,@base+"::") }
- }}}
+ }}}
end
end
