bindings: Transfer C++ documentation strings to Python and Java wrappers.

.gitignore

@@ -45,12 +45,14 @@ Makefile.in
 
 # Files generated by building C++ bindings
 doxy/
+bindings/cxx/doxy/
 bindings/cxx/include/libsigrok/enums.hpp
 bindings/cxx/enums.cpp
 bindings/cxx/enums.timestamp
 
 # Files generated by building Python bindings
 *.pyc
+bindings/python/sigrok/core/doc.i
 bindings/python/dist/
 bindings/python/build
 bindings/python/libsigrok.egg-info/
@@ -65,6 +67,7 @@ bindings/python/timestamp
 
 # Files generated by building Java bindings
 *.class
+bindings/java/org/sigrok/core/classes/doc.i
 bindings/java/org/sigrok/core/classes/*.java
 bindings/java/org/sigrok/core/classes/classes_wrap.cxx
 bindings/java/libsigrok_java_core_classes.so

Makefile.am

@@ -425,6 +425,7 @@ bindings/cxx/classes.lo: bindings/cxx/classes.cpp bindings/cxx/enums.cpp \
 
 cxx-clean:
 	rm -rf doxy/
+	rm -rf bindings/cxx/doxy/
 	rm -f bindings/cxx/enums.cpp
 	rm -f bindings/cxx/include/libsigrok/enums.hpp
 	rm -f bindings/cxx/enums.timestamp
@@ -433,9 +434,19 @@ CLEAN_EXTRA += cxx-clean
 
 endif
 
+CPPXMLDOC = bindings/cxx/doxy/xml/index.xml
+
+$(CPPXMLDOC): bindings/cxx/include/libsigrok/libsigrok.hpp \
+		bindings/cxx/enums.timestamp
+	$(AM_V_GEN)cd bindings/cxx && doxygen Doxyfile
+
 if BINDINGS_PYTHON
 
 PDIR = bindings/python
+PDOC = bindings/python/sigrok/core/doc.i
+
+$(PDOC): bindings/swig/doc.py $(CPPXMLDOC)
+	$(AM_V_GEN)python bindings/swig/doc.py python $(CPPXMLDOC) > $@
 
 python-build: $(PDIR)/timestamp
 
@@ -444,7 +455,7 @@ python-quietclean:
 		| grep -v "can.t clean it"; true
 
 $(PDIR)/timestamp: bindings/cxx/libsigrokxx.la $(PDIR)/sigrok/core/classes.i \
-		bindings/swig/classes.i $(library_include_HEADERS)
+		bindings/swig/classes.i $(PDOC) $(library_include_HEADERS)
 	$(AM_V_at)$(MAKE) python-quietclean
 	$(AM_V_GEN)cd $(PDIR) && python setup.py --quiet build 3>&1 1>&2 2>&3 \
 		| grep -v "command line option.*Wstrict-prototypes"; true
@@ -471,13 +482,17 @@ JCLS = $(JDIR)/$(JPKG)/classes
 JINT = $(JDIR)/$(JPKG)/interfaces
 JSRC = $(JCLS)/*.java $(JINT)/*.java
 JSWG = $(JCLS)/classes.i
+JDOC = $(JCLS)/doc.i
 JCXX = $(JCLS)/classes_wrap.cxx
 JLIB = $(JDIR)/libsigrok_java_core_classes.so
 JJAR = $(JDIR)/sigrok-core.jar
 
 java-build: $(JJAR) $(JLIB)
 
-$(JCXX): $(JSWG) bindings/swig/classes.i $(library_include_HEADERS)
+$(JDOC): bindings/swig/doc.py $(CPPXMLDOC)
+	$(AM_V_GEN)python bindings/swig/doc.py java $(CPPXMLDOC) > $@
+
+$(JCXX): $(JSWG) $(JDOC) bindings/swig/classes.i $(library_include_HEADERS)
 	$(AM_V_GEN)swig -c++ -java -package org.sigrok.core.classes \
 		-Iinclude -Ibindings/cxx/include -outdir $(JCLS) $(JSWG)
 

bindings/cxx/Doxyfile

@@ -683,7 +683,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES
@@ -1779,7 +1779,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1808,7 +1808,7 @@ XML_DTD                =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_PROGRAMLISTING     = YES
+XML_PROGRAMLISTING     = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to the DOCBOOK output

bindings/java/org/sigrok/core/classes/classes.i

@@ -345,4 +345,5 @@ typedef jobject jsourcecallback;
 /* Currently broken due to some std::map typemap issues. */
 %ignore sigrok::Meta::get_config;
 
+%include "doc.i"
 %include "bindings/swig/classes.i"

bindings/python/sigrok/core/classes.i

@@ -332,6 +332,8 @@ std::map<std::string, Glib::VariantBase> dict_to_map_options(PyObject *dict,
 %ignore sigrok::InputFormat::open_file;
 %ignore sigrok::OutputFormat::create_output;
 
+%include "doc.i"
+
 %include "../../../swig/classes.i"
 
 /* Support Driver.scan() with keyword arguments. */

bindings/swig/doc.py

@@ -0,0 +1,59 @@
+##
+## This file is part of the libsigrok project.
+##
+## Copyright (C) 2014 Martin Ling <martin-sigrok@earth.li>
+##
+## This program is free software: you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with this program.  If not, see <http://www.gnu.org/licenses/>.
+##
+
+from xml.etree import ElementTree
+import sys, os
+
+language, input_file = sys.argv[1:]
+input_dir = os.path.dirname(input_file)
+
+index = ElementTree.parse(input_file)
+
+def get_text(node):
+    paras = node.findall('para')
+    return str.join('\n\n', [p.text.rstrip() for p in paras if p.text])
+
+for compound in index.findall('compound'):
+    if compound.attrib['kind'] != 'class':
+        continue
+    class_name = compound.find('name').text
+    if not class_name.startswith('sigrok::'):
+        continue
+    doc = ElementTree.parse("%s/%s.xml" % (input_dir, compound.attrib['refid']))
+    cls = doc.find('compounddef')
+    brief = get_text(cls.find('briefdescription'))
+    if brief:
+        if language == 'python':
+            print '%%feature("docstring") %s "%s";' % (class_name, brief)
+        elif language == 'java':
+            print '%%typemap(javaclassmodifiers) %s "/** %s */\npublic class"' % (
+            class_name, brief)
+    for section in cls.findall('sectiondef'):
+        if section.attrib['kind'] != 'public-func':
+            continue
+        for function in section.findall('memberdef'):
+            function_name = function.find('name').text
+            brief = get_text(function.find('briefdescription'))
+            if brief:
+                if language == 'python':
+                    print '%%feature("docstring") %s::%s "%s";' % (
+                        class_name, function_name, brief)
+                elif language == 'java':
+                    print '%%javamethodmodifiers %s::%s "/** %s */\npublic"' % (
+                    class_name, function_name, brief)