Re: [Epydoc-devel] Docstring parsing shortcomings
Brought to you by:
edloper
From: Hans M. <me...@in...> - 2007-05-11 11:46:22
|
Am Freitag, 11. Mai 2007 13:34:01 schrieb Hans Meine: > Actually, I remember having read that the upcoming boost 1.34.0 has such a > feature, that is why I asked a student to try that out, but he told me that > it hadn't. Still, a quick search brings up this: > http://lists.boost.org/Archives/boost/2007/04/120397.php > ..which tells us that "Boost.Python now automatically appends C++ > signatures to docstrings.". (Note that "C++ signatures" include full C++ > type specs before the argument names, and may not even contain the names if > they were not specified..) > > I will try that out myself now and report back. OK, after some struggling with the changed build system, which is incompatible with our university's NFS layout, I found that it works indeed (no clue why I was told that it does not work). Here are some examples: Function exported without any doc markup: In [2]: applyFourierFilter.__doc__ Out[2]: 'C++ signature:\n applyFourierFilter(vigra::PythonFixedBandsImage<float>, vigra::PythonFixedBandsImage<float>) -> vigra::PythonFixedBandsImage<vigra::TinyVector<float, 2> >' The same, but a method of the class Diff2D: In [4]: Diff2D.norm.__doc__ Out[4]: 'C++ signature:\n norm(vigra::Diff2D {lvalue}) -> double' Function exported with argument names, but no docstring: In [5]: oversamplingGradient.__doc__ Out[5]: 'C++ signature:\n oversamplingGradient(vigra::PythonSingleBandImage image, double sigma, bool withOffset=False) -> vigra::PythonFixedBandsImage<vigra::TinyVector<float, 2> >' Function exported with both docstring (incl. signature) and argument names: In [6]: susanDiscWindow.__doc__ Out[6]: 'susanDiscWindow(image, threshold, radius = 3.4, similarityExponent = 6.0)\nthreshold: grayvalue similarity threshold\nradius: radius of the circular window (default 3.4 -> 37 pixels)\nsimilarityExponent: exponent of the Gaussian similarity measure\nC++ signature:\n susanDiscWindow(vigra::PythonImage image, double threshold, double radius=3.3999999999999999, double similarityExponent=6.0) -> vigra::PythonFixedBandsImage<float>' That is, boost::python indeed *appends* the C++ signature to the docstring, prepending a unique prefix as you can see. There is support for switching the signatures off, and one can even disable all docstrings, but the format seems to be fixed, hard-coded, and parsable: > docstring_options(bool show_all=true); > > Effects: Constructs a docstring_options object which controls the > appearance of function and member-function docstrings defined in the > code that follows. If show_all is true, both the user-defined > docstrings and the automatically generated C++ signatures are > shown. If show_all is false the __doc__ attributes are None. > > docstring_options(bool show_user_defined, bool show_signatures); > > Effects: Constructs a docstring_options object which controls the > appearance of function and member-function docstrings defined in the > code that follows. Iff show_user_defined is true, the user-defined > docstrings are shown. Iff show_signatures is true, C++ signatures are > automatically added. If both show_user_defined and show_signatures are > false, the __doc__ attributes are None. Hope that helps. -- Ciao, / / /--/ / / ANS |