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

[Tom Rondeau]

On Mon, Oct 17, 2011 at 12:36 PM, Josh Blum <address@hidden> wrote:

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). :-)

That's great, Josh, thanks! I'll look at it soon, but sounds like a good, sane way of doing this.

One question: what if the user's don't have doxygen installed? Right now it's only an optional dependency. My guess is that it's not too hard to turn this on or off depending on if you have doxygen. I just want to make sure this is handled.

Since we're all hoping that we get to move to cmake completely, I'm going to abandon any work on getting this to work in autotools.

 

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

I agree. It would be nice to have all the documentation for every function, not just the class docs.

Thanks!

Tom

 

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

_______________________________________________
Discuss-gnuradio mailing list
address@hidden
https://lists.gnu.org/mailman/listinfo/discuss-gnuradio