[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Discuss-gnuradio] Ben's docstring work
From: |
Ben Reynwar |
Subject: |
Re: [Discuss-gnuradio] Ben's docstring work |
Date: |
Mon, 17 Oct 2011 21:58:42 -0700 |
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")
>
- Re: [Discuss-gnuradio] Ben's docstring work, (continued)
- Re: [Discuss-gnuradio] Ben's docstring work, Josh Blum, 2011/10/15
- Re: [Discuss-gnuradio] Ben's docstring work, Ben Reynwar, 2011/10/15
- Re: [Discuss-gnuradio] Ben's docstring work, Josh Blum, 2011/10/15
- Re: [Discuss-gnuradio] Ben's docstring work, Ben Reynwar, 2011/10/16
- Re: [Discuss-gnuradio] Ben's docstring work, Ben Reynwar, 2011/10/16
- Message not available
- Re: [Discuss-gnuradio] Ben's docstring work, Ben Reynwar, 2011/10/16
- Re: [Discuss-gnuradio] Ben's docstring work, Josh Blum, 2011/10/17
- Re: [Discuss-gnuradio] Ben's docstring work, Tom Rondeau, 2011/10/17
- Re: [Discuss-gnuradio] Ben's docstring work, Josh Blum, 2011/10/17
- Re: [Discuss-gnuradio] Ben's docstring work, Tom Rondeau, 2011/10/17
- Re: [Discuss-gnuradio] Ben's docstring work,
Ben Reynwar <=