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

[Josh Blum]

Ahhh much better. I added generation for a few of the components in core
(general, gengen, filter, io)
http://gnuradio.org/cgit/jblum.git/commit/?h=swig_docs&id=d65572359a74e97ee6a01d89dcc44fd77ce54fef

Basically, its pretty nice. The xml only regenerates when header files
change, and the swig docs.i only regenerate when the xml is changed, and
so on. No checked-in generated files. XML generation is very quick. Your
python script actually takes a bit longer (but im not complaining). :-)

I would like to get the grc docs parser looking for __doc__ strings soon.

A few comments on your doc generator. Im not sure we agree on a standard
here for documenting headers... but useful doc blocks may be in several
places in the header:

1) docs for the factor/make function
2) docs for class definition
3) docs just in the header, think \file

It looks like the generated docstrings only gets one of these. I suggest
concatenating all forms of docs into the one class docstring so the full
amount of docs is available at runtime to python.

-Josh

> 
> 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")