--- /dev/null
+#
+# Copyright 2005 Free Software Foundation, Inc.
+#
+# This file is part of GNU Radio
+#
+# GNU Radio 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, or (at your option)
+# any later version.
+#
+# GNU Radio 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 GNU Radio; see the file COPYING. If not, write to
+# the Free Software Foundation, Inc., 51 Franklin Street,
+# Boston, MA 02110-1301, USA.
+#
+
+#
+# Generating Python docstrings from C++ code using doxygen
+#
+
+There are at least two strategies for this:
+ - use xsltproc as described below
+ - use doxy2swig.py (included in this directory)
+
+FIXME: get one of these working (probably doxy2swig since it doesn't
+add any additional dependencies).
+
+----------------------------------------------------------------
+
+Note: Robin's patch is in SWIG >= 1.3.23
+
+--------------------------------------------------------------------------------
+From: http://mailman.cs.uchicago.edu/pipermail/swig/2004-October/010604.html
+
+> I applied the docstring patch. '%feature("autodoc",1");' is working as
+> expected ...
+
+[problem solved. ...]
+
+> I can not agree more with the doxygen idea. I am using doxygen for
+> documentation and I have been trying to put doxygen output to the
+> python interface. Automatic generation of %feature("docstring") lines
+> from doxygen output is the closest solution I can think of but the
+> workload is still pretty big. How I wish this feature can be
+> implemented in the near future.
+
+I have successfully extracted function/class description from doxygen
+generated xml files, using an xslt script. To add doxygen generated
+description to each class/function, you will need to (tested under
+linux, note that this works only for Python, using Robin's docstring
+patch)
+
+1. download swig source, apply Robin's docstring patch from
+ https://sourceforge.net/tracker/index.php?func=detail&aid=1023309&group_id=1645&atid=301645
+ compile and install
+
+2. generate doxygen document with option "GENERATE_XML = YES"
+
+3. copy the attached script (save as swig.xsl) to the doc/xml directory
+ and run
+
+ > xsltproc swig.xsl index.xml > temp_doc.i
+ > cat temp_doc.i | sed 's/"/\\"/g' | sed 's/__QuOtE__/"/g' > swig_doc.i
+
+ you will get an interface file with lines like
+ %feature("docstring") class "class description";
+ %feature("docstring") class::function "member function
+ description";
+
+ the second step is necessary since there might be " in descriptions
+ and I need to backquote them before I replace __QuOtE__ by real
+ quotes. (xslt experts may know how to post-process <xsl:value-of> and
+ make the script easier to use.)
+
+4. in your interface file, add
+ %include "siwg_doc.i"
+ %feature("autodoc","1") ;
+
+Hope this helps.
+
+swig.xsl:
+=========================================================
+
+<!-- XSLT script to extract document for class/function for swig docstring
+ If you have xsltproc you could use:
+ xsltproc swig.xsl index.xml > swig_doc.i
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+ <xsl:output method="text"/>
+ <xsl:template match="/">
+ <!-- process each compound -->
+ <xsl:for-each select="doxygenindex/compound">
+ <xsl:apply-templates select="document( concat( @refid, '.xml' ) )/*" />
+ </xsl:for-each>
+ </xsl:template>
+
+ <xsl:template match="doxygen">
+ <xsl:for-each select="compounddef[@kind='class']">
+ <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text>
+ <xsl:value-of select="compoundname"/>
+ <xsl:text> __QuOtE__ </xsl:text>
+ <xsl:value-of select="briefdescription"/><xsl:text>
+ </xsl:text>
+ <xsl:value-of select="detaileddescription"/>
+ <xsl:text> see also: </xsl:text>
+ <xsl:value-of select="includes"/>
+ <xsl:text>__QuOtE__; </xsl:text>
+
+ <!-- output for each function individually -->
+ <xsl:for-each select="*/memberdef[@kind='function' and not(starts-with(name,'operator'))]">
+ <xsl:text>%feature(__QuOtE__docstring__QuOtE__) </xsl:text><xsl:value-of select="../../compoundname"/>::<xsl:value-of select="name"/>
+ <xsl:text> __QuOtE__ </xsl:text>
+ <xsl:value-of select="definition"/> <xsl:value-of select="argsstring"/>
+ <xsl:text>
+ </xsl:text><xsl:value-of select="briefdescription"/><xsl:text>
+ </xsl:text><xsl:value-of select="detaileddescription"/>
+ <xsl:text>__QuOtE__; </xsl:text>
+ </xsl:for-each>
+ </xsl:for-each>
+ </xsl:template>
+</xsl:stylesheet>
+
+--
+Bo Peng
\ No newline at end of file
projects / debian / gnuradio / blobdiff