Generate doxygen comments for Session_0_10 using AMQP <doc> elements.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@590512 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 81 insertions, 12 deletions

diff --git a/cpp/rubygen/amqpgen.rb b/cpp/rubygen/amqpgen.rb
index 5952b494df..efd5b024ac 100755
--- a/cpp/rubygen/amqpgen.rb
+++ b/cpp/rubygen/amqpgen.rb
@@ -89,7 +89,7 @@ end
 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 @@ class AmqpElement
     @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
@@ -129,6 +129,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
   amqp_attr_reader :type
diff --git a/cpp/rubygen/cppgen.rb b/cpp/rubygen/cppgen.rb
index 2590d48f7b..5db5793649 100755
--- a/cpp/rubygen/cppgen.rb
+++ b/cpp/rubygen/cppgen.rb
@@ -235,6 +235,12 @@ class CppGen < Generator
     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
diff --git a/cpp/rubygen/templates/Session.rb b/cpp/rubygen/templates/Session.rb
index c61a217682..167422d3a9 100644
--- a/cpp/rubygen/templates/Session.rb
+++ b/cpp/rubygen/templates/Session.rb
@@ -11,22 +11,38 @@ class CppGen
       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 @@ class SessionNoKeywordGen < CppGen
         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 @@ EOS
           }}}}
 
     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 @@ class SessionGen < CppGen
             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 @@ class SessionGen < CppGen
           public
           genl "#{@classname}() {}"
           keyword_methods.each { |m| gen_keyword_decl(m,@base+"::") }
-       }}}
+        }}}
   end
 end