From bd4fda24074ce175d23a59cb15cceb19707fe6f1 Mon Sep 17 00:00:00 2001 From: Martin Ling Date: Fri, 1 Aug 2014 18:17:33 +0100 Subject: [PATCH] bindings: Transfer C++ documentation strings to Python and Java wrappers. --- .gitignore | 3 + Makefile.am | 19 +++++- bindings/cxx/Doxyfile | 6 +- .../java/org/sigrok/core/classes/classes.i | 1 + bindings/python/sigrok/core/classes.i | 2 + bindings/swig/doc.py | 59 +++++++++++++++++++ 6 files changed, 85 insertions(+), 5 deletions(-) create mode 100644 bindings/swig/doc.py diff --git a/.gitignore b/.gitignore index 21e039a2..4d6c577a 100644 --- 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 44bc9598..bddae723 100644 --- 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 6d4b1538..9cef48af 100644 --- 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 52eace85..633ecdbe 100644 --- 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 126991b7..ba70d224 100644 --- a/bindings/python/sigrok/core/classes.i +++ b/bindings/python/sigrok/core/classes.i @@ -332,6 +332,8 @@ std::map 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 index 00000000..16cc1652 --- /dev/null +++ b/bindings/swig/doc.py @@ -0,0 +1,59 @@ +## +## This file is part of the libsigrok project. +## +## Copyright (C) 2014 Martin Ling +## +## 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 . +## + +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)