discuss-gnuradio
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Tom Rondeau
Subject: Re: [Discuss-gnuradio] Ben's docstring work
Date: Wed, 16 Nov 2011 17:57:34 -0500

Ben, Josh,
Where are we with this? We had good momentum and were like 95% there, but then we dropped it about a month ago. I believe that Josh had a branch that, using cmake, took the docstrings code and would build a .i file per top-level component and install it with the Python code. I think the issue was that this only got the constructors, but Ben's note here talks about fixing that. Has this been ported to the cmake build process to autogenerate the doc strings?

Thanks,
Tom


On Tue, Oct 18, 2011 at 12:58 AM, Ben Reynwar <address@hidden> wrote:
I've made a few changes to doxyxml so that the DoxyFile objects should
be exposing their descriptions and have changed swig_doc.py so that
it's grabbing documentation from the file if it is present.  It
doesn't appear to be picking any file descriptions up and I'm not sure
if that's because it's not working or because there aren't any.  If
you know of some good blocks to test it on let me know.
commit is https://github.com/benreynwar/gnuradio/commit/d6e36498174dcb20f92369cc6097514a5d102ded

At the moment the layout for a docstring for a python creator function:

"""
brief description from class

detailed description from class

brief description from make func

detailed description from make func

brief description from file

detailed description from file

Params: (list of input parameters)
"""

The docstring for the class itself is the same without the parameter
list at the end.

Cheers,
Ben

On Mon, Oct 17, 2011 at 9:36 AM, 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). :-)
>
> 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")
>

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]