<div dir="ltr">On Fri, Aug 15, 2014 at 8:06 AM, Richard Gildea <span dir="ltr"><<a href="mailto:rgildea@gmail.com" target="_blank">rgildea@gmail.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>I had a go at starting to document cctbx.uctbx.unit_cell, which as you know is mainly a Boost.Python extension (<a href="https://sourceforge.net/p/cctbx/code/20467/" target="_blank">https://sourceforge.net/p/cctbx/code/20467/</a>). Before I travel too much further down this route, is this an appropriate way of documenting Boost.Python extensions or is there a better way we can do this?</div>
</div></blockquote><div><br></div><div>I haven't had enough time to experiment to decide on the best approach. I see three choices - the first is what you've done:</div><div><br></div><div>class my_class (ext.my_class) :</div>
<div> """doc"""</div><div><br></div><div> def boosted_function (self, some_argument) :</div><div> """function doc"""</div><div> super(ext.my_class, self).boosted_function(some_argument)</div>
<div><br></div><div>OR (2):</div><div><br></div><div>ext.my_class.__doc__ = """doc"""</div><div>ext.my_class.boosted_function.__func__.__doc__ = """function doc"""</div>
<div><br></div><div>OR (3):</div><div><br></div><div>put the docstrings in C++ code, for instance:</div><div><br></div><div>.def("boosted_function", &my_class::boosted_function, "function doc")</div>
<div><br></div><div>(not sure what the equivalent is for classes but it's probably pretty similar)</div><div><br></div><div>My opinion is that (1) is much too prone to confusion and API conflicts unless we're already using this code structure (and FYI, you broke the call signatures for a couple of methods). (3) is just gross. (2) is also gross but has the virtue of being the least likely to break, and doesn't require modifying C++ files. So I'm inclined to take that approach</div>
<div><br></div><div>(For what it's worth, when modifying a class using the boost.python injector, we appear to be able to set __doc__ inside there; see iotbx.pdb.hierarchy for an example.)</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><div>It would be good to get the documentation for the core cctbx classes up and running, however several of the core classes (e.g. cctbx.sgtbx.space_group, cctbx.uctbx.unit_cell, flex arrays) are mostly Boost.Python extensions, so it would be good to arrive at a sensible way to document these extensions.</div>
</div></blockquote><div><br></div><div>Agreed. I think for flex arrays we will be stuck writing the docstrings in C++ - however since these are relatively stable APIs it should be reasonably straightforward.</div><div><br>
</div><div>-Nat</div></div></div></div>