Thread: [Epydoc-devel] __init__ params for extension type?
Brought to you by:
edloper
From: Barry W. <ba...@py...> - 2006-07-12 15:58:42
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 FTR: still currently using epydoc 2.1 Where would I document the parameters for extension types? I thought I could add @param and @type fields to the docstring for the tp_doc slot, but when I generate the documentation I just get warnings like: In foo.Bar docstring: - Warning: Invalid context for field tag 'param' In the generated documentation for the class's __init__() you see: x.__init__(...) initializes x; see x.__class__.__doc__ for signature but there appears to be no way to document that signature. Or have I just screwed up somewhere? ;) Thanks, - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.3 (Darwin) iQCVAwUBRLUcL3EjvBPtnXfVAQLDYwP/T2znjaNLKAeN+uG4nQWZ5S9JZ3iAnjmo RoB1RuuzdcgZJF4qIcSxNDwDCT1izsA1ml2YLByxEO+OREbNZ8SqJhXEbUPJ5P3u 2gbIUrii+sFcd+4DnoB4hi62tskDNvmAd47HwauzuNKuWHyRKxIW7ZzsR5Nezzq5 G4SKyq48F3g= =sRlD -----END PGP SIGNATURE----- |
From: Edward L. <ed...@gr...> - 2006-07-12 16:22:11
|
On Jul 12, 2006, at 9:58 AM, Barry Warsaw wrote: > FTR: still currently using epydoc 2.1 > > Where would I document the parameters for extension types? I thought > I could add @param and @type fields to the docstring for the tp_doc > slot, but when I generate the documentation I just get warnings like: > > In foo.Bar docstring: > - Warning: Invalid context for field tag 'param' > > In the generated documentation for the class's __init__() you see: > > x.__init__(...) initializes x; see x.__class__.__doc__ for signature Try something like this as your docstring: "x.__init__(a, b, c) -- initializes x, using parameters a, b, and c." This is the convention that's used by most builtin functions, and epydoc understands it. (I.e., epydoc will detect the signature in the docstring, parse it, and extract the variable names.) Epydoc also understands a bunch of variants -- for the details, search for "SIGNATURE_RE" in epydoc/objdoc.py. Once you've provided the signature in the first line of the docstring, you can then use @param, @type, etc., if you want to provide more info about some of the parameters. E.g.: """foo(x,y) -> z -- performs a foo action. @param y: The y parameter for the foo action. Should be positive. @param z: The z parameter for the foo action. Should be negative.""" -Edward |
From: Daniele V. <dan...@gm...> - 2006-07-12 16:43:47
|
> Where would I document the parameters for extension types? I thought > I could add @param and @type fields to the docstring for the tp_doc > slot, but when I generate the documentation I just get warnings like: > > In foo.Bar docstring: > - Warning: Invalid context for field tag 'param' > > In the generated documentation for the class's __init__() you see: > > x.__init__(...) initializes x; see x.__class__.__doc__ for signature > > but there appears to be no way to document that signature. Or have I > just screwed up somewhere? ;) The string x.__init__(...) initializes x; see x.__class__.__doc__ for signature is just "object.__init__" docstring. Actually this is in contrast with PEP 257, which informs: The class constructor should be documented in the docstring for its __init__ method. Epydoc treats __init__ as a normal method (at least from this PoV): the ctor parameters should be added to the __init__ docstring. Example: class Foo(object): """This is the object signature""" def __init__(self, a, b): """The ctor. @param a: The first letter @type a: int @param b: The letter after the first @type b: str """ pass Is this a problem for extension types? I guess the __init__.__doc__ can be customized. @Edward: In any case, allowing the constructor signature to be expressed in the class docstring seems reasonable. I saw the same convention used somewhere, just as the object __init__ docstring suggests. |
From: Barry W. <ba...@py...> - 2006-07-12 16:53:06
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Jul 12, 2006, at 12:43 PM, Daniele Varrazzo wrote: > The string > > x.__init__(...) initializes x; see x.__class__.__doc__ for > signature > > is just "object.__init__" docstring. Actually this is in contrast with > PEP 257, which informs: > > The class constructor should be documented in the docstring for its > __init__ method. > > Epydoc treats __init__ as a normal method (at least from this PoV): > the ctor parameters should be added to the __init__ docstring. > Example: > > class Foo(object): > """This is the object signature""" > def __init__(self, a, b): > """The ctor. > > @param a: The first letter > @type a: int > @param b: The letter after the first > @type b: str > """ > pass > > Is this a problem for extension types? I guess the __init__.__doc__ > can be customized. > > @Edward: > In any case, allowing the constructor signature to be expressed in the > class docstring seems reasonable. I saw the same convention used > somewhere, just as the object __init__ docstring suggests. I think this /is/ a problem for extension types. The constructor for an extension type is defined in the tp_init slot of the type struct and the struct's tp_doc slot is the only place that you can hang documentation. AFAICT this slot really serves dual purposes as both the type's (a.k.a. class's) documentation and the documentation for the constructor. There is really no other place to tie documentation to an extension type's __init__(), unlike for other methods which are defined in a PyMethodDef containing slots for both the function and docstring. So it seems like parsing constructor signatures out of a class docstring for extension types is the only option. BTW, I tried Edward's suggestion in my tp_doc docstring and it doesn't really work. The class documentation stops at the first @param and AFAICT just gets thrown away. - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.3 (Darwin) iQCVAwUBRLUo7HEjvBPtnXfVAQIudgQAkm6piVS/81fYStQyST9AqTWr+UCPg/EN jq7g0SbNOjqHM4ZztfS9iRH9FBgb/B2WDHPexgRmvVSowgBhBdADBHWS529A0voq 8mW/u9QCYf4PrHoU0GyF3hn9iBfe/egXIt7xdF+Kb9t1su/WCPqM9Aoxk1qzLR7h NxGBaxR1NpE= =BTOB -----END PGP SIGNATURE----- |
From: Edward L. <ed...@gr...> - 2006-07-13 03:25:20
|
On Jul 12, 2006, at 10:53 AM, Barry Warsaw wrote: >> @Edward: >> In any case, allowing the constructor signature to be expressed in >> the >> class docstring seems reasonable. I saw the same convention used >> somewhere, just as the object __init__ docstring suggests. > > I think this /is/ a problem for extension types. The constructor for > an extension type is defined in the tp_init slot of the type struct > and the struct's tp_doc slot is the only place that you can hang > documentation. AFAICT this slot really serves dual purposes as both > the type's (a.k.a. class's) documentation and the documentation for > the constructor. Ah, I hadn't realized that there was no way to give the class & the constructor separate docstrings for extension classes. In that case, this definitely should be supported. I.e., epydoc should check the class docstring to see if it starts with a signature-like line, and if so, derive the constructor signature from it, and create a new documentation entry for the constructor. This should probably only be done for builtin/extension classes, not pure python classes. Unfortunately, I won't have time to work on this for a little while. But if anyone wants to put together a patch to do this (for epydoc 3, or 2, or both), that would be great! :) > BTW, I tried Edward's suggestion in my tp_doc docstring and it > doesn't really work. The class documentation stops at the first > @param and AFAICT just gets thrown away. I was assuming that the constructor had its own docstring, just like other methods. If that's not the case, then this won't work. :) -Edward |
From: Barry W. <ba...@py...> - 2006-07-13 21:34:08
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Jul 12, 2006, at 11:25 PM, Edward Loper wrote: > Ah, I hadn't realized that there was no way to give the class & the > constructor separate docstrings for extension classes. In that > case, this definitely should be supported. I.e., epydoc should > check the class docstring to see if it starts with a signature-like > line, and if so, derive the constructor signature from it, and > create a new documentation entry for the constructor. This should > probably only be done for builtin/extension classes, not pure > python classes. > > Unfortunately, I won't have time to work on this for a little > while. But if anyone wants to put together a patch to do this (for > epydoc 3, or 2, or both), that would be great! :) I may indeed work on this and will definitely provide any patches I come up with. Cheers - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.3 (Darwin) iQCVAwUBRLa8SnEjvBPtnXfVAQJETwP/XXUvlkErGfQ4n6QejLtbvL9ETuce2SLe pTGIj4EH3/6xm2EMTCAKri5KxC5TFqh9B1IMbzzH4PBihijbhcZDRPVGNEk0vhLM FgIME5/o9b+mdWpHlNRBSh8oRd2nKvH2YBuohYFsmz18p1eMyCnJhtDqOE3gVATp r7LkpTajj6Q= =DPoT -----END PGP SIGNATURE----- |
From: Barry W. <ba...@py...> - 2006-10-03 20:13:22
|
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Sep 27, 2006, at 3:42 PM, Daniele Varrazzo wrote: > a few days ago i patched Epydoc adding the functionality we talked > about. The feature has been merged in the svn trunk in r1396. Thanks very much Daniele. I'll try to pull down this version and run it over our code. Cheers, - -Barry -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (Darwin) iQCVAwUBRSLEWHEjvBPtnXfVAQKHjAP/UzjP4WTLrL2OzQUm88aI1RyrS+hzp3xt 0GRqmCVcvidCQNu57e07pMoEgfoCJeO+Cm4OLy6U9ioAR+Kr1o2cSSFDed+EUmi4 CFI1SP8v2t+D+PSbY3hAYiWYiKD2YX5QavivJAwvU31EbUitD3PFctkpJbDdjsvb JyJWaSzbAW8= =10nj -----END PGP SIGNATURE----- |