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

[Josh Blum]

On 10/17/2011 10:46 AM, Tom Rondeau wrote:
> 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.
> 

Right now its generating an empty swig docs file if doxygen was not
found. In other words, everything will still build.

Also, as long as cmake can find the doxygen executable, it will perform
the generation. The way to turn this off right now is to tell cmake that
the doxygen executable is undefined/not-found. I would like to add a
more official option: either it gets its own option, or its part of the
existing ENABLE_DOXYGEN option.

Now having said that, the time taken to compile the swig generated cc
file >> than the time taken to generate the docs. So its really just
fine to always build the docs as far as I am concerned.

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

If we want to keep autotools working along-side cmake w/ this doc work,
autotools would need to generate an empty swig_docs.i file to keep the
compile happy.

-josh

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