Return-Path: 
 <qpid-commits-return-3932-apmail-incubator-qpid-commits-archive=incubator.apache.org@incubator.apache.org>
Delivered-To: apmail-incubator-qpid-commits-archive@locus.apache.org
Received: (qmail 35847 invoked from network); 30 Oct 2007 23:37:16 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2)
  by minotaur.apache.org with SMTP; 30 Oct 2007 23:37:16 -0000
Received: (qmail 87706 invoked by uid 500); 30 Oct 2007 23:37:04 -0000
Delivered-To: apmail-incubator-qpid-commits-archive@incubator.apache.org
Received: (qmail 87669 invoked by uid 500); 30 Oct 2007 23:37:04 -0000
Mailing-List: contact qpid-commits-help@incubator.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:qpid-commits-help@incubator.apache.org>
List-Unsubscribe: <mailto:qpid-commits-unsubscribe@incubator.apache.org>
List-Post: <mailto:qpid-commits@incubator.apache.org>
List-Id: <qpid-commits.incubator.apache.org>
Reply-To: qpid-dev@incubator.apache.org
Delivered-To: mailing list qpid-commits@incubator.apache.org
Received: (qmail 87434 invoked by uid 99); 30 Oct 2007 23:37:04 -0000
Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 30 Oct 2007 16:37:03 -0700
X-ASF-Spam-Status: No, hits=-100.0 required=10.0
	tests=ALL_TRUSTED
X-Spam-Check-By: apache.org
Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3)
    by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 30 Oct 2007 23:37:03 +0000
Received: by eris.apache.org (Postfix, from userid 65534)
	id D382D1A9832; Tue, 30 Oct 2007 16:36:30 -0700 (PDT)
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r590512 - in /incubator/qpid/trunk/qpid/cpp/rubygen:
 amqpgen.rb
 cppgen.rb templates/Session.rb
Date: Tue, 30 Oct 2007 23:36:29 -0000
To: qpid-commits@incubator.apache.org
From: aconway@apache.org
X-Mailer: svnmailer-1.0.8
Message-Id: <20071030233631.D382D1A9832@eris.apache.org>
X-Virus-Checked: Checked by ClamAV on apache.org

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 @@
     @cache_children[nil]=@children
   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 #{@amqp.version} session API."
+            genl @amqp.class_("session").doc
+          }
           cpp_class(@classname) {
             public
             gen <<EOS
 #{@classname}();
+
+/** 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;
 #{@classname}::#{@classname}() {}
@@ -166,6 +200,30 @@
             genl "BOOST_PARAMETER_KEYWORD(keyword_tags, #{k})"
           }}
         genl
+        # Doxygen comment.
+        doxygen_comment {
+          genl "AMQP #{@amqp.version} session API with keyword arguments."
+          genl <<EOS
+This class provides the same set of functions as #{@base}, 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:
+
+@code
+session.foo(1,2,3);             // Normal no keywords
+session.foo(arg::z=3, arg::x=1); // Keywords and a default
+@endcode
+
+The keyword functions are easy to use but their declarations are hard
+to read. You may find it easier to read the documentation for #{@base}
+which provides the same set of functions using normal non-keyword
+declarations.
+
+EOS
+        }
+        # Session class.
         cpp_class(@classname,"public #{@base}") {
           private
           genl "#{@classname}(shared_ptr<SessionCore> core) : #{ @base}(core) {}"
@@ -174,7 +232,7 @@
           public
           genl "#{@classname}() {}"
           keyword_methods.each { |m| gen_keyword_decl(m,@base+"::") }
-       }}}
+        }}}
   end
 end