Re: [Discuss-gnuradio] Ben's docstring work

[Ben Reynwar]

On Sat, Oct 15, 2011 at 11:33 PM, Josh Blum <address@hidden> wrote:
>
>
> On 10/15/2011 11:30 PM, Ben Reynwar wrote:
>> On Sat, Oct 15, 2011 at 10:58 PM, Ben Reynwar <address@hidden> wrote:
>>> On Sat, Oct 15, 2011 at 4:16 PM, Josh Blum <address@hidden> wrote:
>>>>
>>>>>
>>>>> Hi Josh,
>>>>>
>>>>> The docstrings should be accessible using the __doc__ property in the
>>>>> normal way.
>>>>>
>>>>> If you look at the generated python file the docstrings should be
>>>>> present in the function and class definitions as usual.
>>>>> e.g.
>>>>> def kurtolic_equalizer_cc(blah blah):
>>>>>     "docstring here"
>>>>>     blah blah blah
>>>>>
>>>>> If that's not happening, then it's not working.
>>>>>
>>>>
>>>> Looks like i did it wrong then. But I cant see anything wrong with the
>>>> process. :-)
>>>>
>>>> python -c "from gnuradio import digital; print
>>>> digital.kurtotic_equalizer_cc.__doc__"
>>>>
>>>> kurtotic_equalizer_cc(int num_taps, float mu) ->
>>>> digital_kurtotic_equalizer_cc_sptr
>>>>
>>>>> I cloned your repo and checked out your swig_docs branch but got a
>>>>> compilation error.
>>>>>
>>>>> [ 46%] Generating gengen/gr_peak_detector_fb.i,
>>>>> gengen/gr_peak_detector_ib.i, gengen/gr_peak_detector_sb.i
>>>>> [ 51%] Built target gengen_generated
>>>>> [ 51%] Swig source
>>>>> [ 52%] Swig source
>>>>> /home/ben/gnuradio-jblum/jblum/gnuradio-core/src/lib/gengen/gengen.i:33:
>>>>> Error: Unable to find 'gengen_generated.i'
>>>>> make[2]: *** 
>>>>> [gnuradio-core/src/lib/swig/gnuradio_core_gengenPYTHON_wrap.cxx]
>>>>> Error 1
>>>>> make[1]: *** 
>>>>> [gnuradio-core/src/lib/swig/CMakeFiles/_gnuradio_core_filter.dir/all]
>>>>> Error 2
>>>>> make: *** [all] Error 2
>>>>>
>>>>
>>>> Ah, yea, I fixed that this morning but forgot to push. Just re-checkout
>>>> the repo.
>>>>
>>>> -Josh
>>>>
>>>
>>> So, it's a bug in swig_doc.py, but I haven't worked out where yet..
>>> It should be generating a docstring for "kurtotic_equalizer_cc", but
>>> it is generating it for "digital_make_kurtotic_equalizer_cc" instead.
>>> There's some stuff in swig_doc.py that determines whether a class or
>>> function is part of a "Block" or just a normal class or function.
>>> That appears to be not working.  I'll see if I can work out why not.
>>>
>>
>
>
> It wouldnt be so bad to parameterize the package name for swig_doc.py.
> Each invocation of the generation macro would just need to pass this
> package name into the python script like so:
>
> python swig_doc.py $builddir/gr-digital/swig/doxygen/xml
> $builddir/gr-digital/swig/swig_doc.i digital
>
> ... if that makes life easier
>
>> Nope, that wasn't the problem.  I have no idea why it's not working.
>> I'll have another look at it tomorrow night.
>
> ok cool
>
> im looking forward to generating docs for each package, and getting grc
> to read the docstrings rather than the xml
>
>

It was the position of the %include "swig_doc.i" in the digital_swig.i file.
It needs to be at the top rather than at the bottom.
Here's a diff.

diff --git a/gr-digital/swig/digital_swig.i b/gr-digital/swig/digital_swig.i
index c804b5c..f6372b1 100644
--- a/gr-digital/swig/digital_swig.i
+++ b/gr-digital/swig/digital_swig.i
@@ -23,6 +23,8 @@

 %include <gri_control_loop.i>

+%include "swig_doc.i"
+
 %{
 #include "digital_binary_slicer_fb.h"
 #include "digital_clock_recovery_mm_cc.h"
@@ -59,8 +61,6 @@
 %include "digital_cpmmod_bc.i"
 %include "digital_gmskmod_bc.i"

-%include "swig_doc.i"
-
 #if SWIGGUILE
 %scheme %{
 (load-extension-global "libguile-gnuradio-digital_swig"
"scm_init_gnuradio_digital_swig_module")