On Mon, Oct 17, 2011 at 11:31 AM, Josh Blum <j...@joshknows.com> wrote:
> > > On 10/17/2011 10:46 AM, Tom Rondeau wrote: > > On Mon, Oct 17, 2011 at 12:36 PM, Josh Blum <j...@joshknows.com> 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. > Perfect! > 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. > I think we just wrap it into the ENABLE_DOXYGEN that's also contingent on Python being enabled. Doesn't really make sense to build the docs and the Python swig and not put the two together now that we can do it. > 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. Yeah, sounds fine to me, too. > > 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 That's easily done. A tad bit hackish, but if we end up keeping the autotools stuff, I can go in and do it right. This is just to keep us going in parallel until we can move over to cmake completely. Thanks, Tom > > >> 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 > >> Discuss-gnuradio@gnu.org > >> https://lists.gnu.org/mailman/listinfo/discuss-gnuradio > >> > > >
_______________________________________________ Discuss-gnuradio mailing list Discuss-gnuradio@gnu.org https://lists.gnu.org/mailman/listinfo/discuss-gnuradio
