#
# 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__ &#10;</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__;&#10;&#10;</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__&#10;</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__; &#10;&#10;</xsl:text>
      </xsl:for-each>
    </xsl:for-each>  
  </xsl:template>
</xsl:stylesheet>

--
Bo Peng