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

diff --git a/.gitignore b/.gitignore
index 21e039a27e23dd0f266fe7b74a67e77962976872..4d6c577a6ad7624d00e25f4d7eed54eed0568b6d 100644 (file)
--- a/.gitignore
+++ b/.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

diff --git a/Makefile.am b/Makefile.am
index 44bc959877d11b7e5e79a87d13125389dec259c7..bddae723fc5e01e718b94e48eb447171d5513b6b 100644 (file)
--- a/Makefile.am
+++ b/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)
 

diff --git a/bindings/cxx/Doxyfile b/bindings/cxx/Doxyfile
index 6d4b15383e16d58832a56af2af8f0f0b8a9bb6e6..9cef48afcc9aca2cf471103dda48f43f3fd795fa 100644 (file)
--- a/bindings/cxx/Doxyfile
+++ b/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

diff --git a/bindings/java/org/sigrok/core/classes/classes.i b/bindings/java/org/sigrok/core/classes/classes.i
index 52eace85a7acfc7ed778b6fe07a8d3bf821dcd19..633ecdbee52145287d120295e81b590ab61f6003 100644 (file)
--- a/bindings/java/org/sigrok/core/classes/classes.i
+++ b/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"

diff --git a/bindings/python/sigrok/core/classes.i b/bindings/python/sigrok/core/classes.i
index 126991b7c247d58e8fd8ae75d7eabbee76f0e24c..ba70d2249c8f104eb5a9f7a9d9f6b513ca5cd688 100644 (file)
--- a/bindings/python/sigrok/core/classes.i
+++ b/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. */

diff --git a/bindings/swig/doc.py b/bindings/swig/doc.py
new file mode 100644 (file)
index 0000000..16cc165
--- /dev/null
+++ b/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)