Re: epydoc reST markup for stdlib docstrings

On Apr 13, 2010, at 08:55 PM, David Goodger wrote:

>I'm not a fan of epydoc's conventions (too much like JavaDoc, too
>verbose, too strict). On the other hand, "now is better than never" --
>working code and rough consensus rule. I wouldn't object to making the
>epydoc field conventions *a* standard convention, allowing for others.
>
>Just as choice of markup is very much a matter of personal preference
>(some people *love* dealing with XML directly), choice of API
>documentation semantics is also a personal preference thing. We would
>be wise to allow for choice.

Perhaps it would be useful to survey some popular and/or large Python code
bases to see what is currently being used?  That would be a good start to try
to figure out what the stdlib should recommend.

I do think that we should make strong recommendations for the standard
library, so that we have consistency and good online documentation.  I
personally like epydoc reST format (not JavaDoc) but I'm sure there are other
decent formats.

-Barry

_______________________________________________
Doc-SIG maillist  -  [email protected]
http://mail.python.org/mailman/listinfo/doc-sig

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iQIcBAEBCAAGBQJLxalFAAoJEBJutWOnSwa/gTgP/iBUJwSk3Y19rPdUHnYLI3OC
VOGn0HdJlwJh7She8AUdebUTPVzD9aWiMxiieNyPpQ5wf5LrOGawpqqZjBbvMqmP
lIpfPsOHsxCC3Fal5ZbMSmmSZVlNmAFEyn3KcTA56/r8FHGUh7coXhb/HMpL7tyq
42fk2r9NQC+UPDRj9wQUD5MCv+cpokCTluzKm3sYjdO20PbzbHr37AMRHHRke6mP
0ewwdmosg3RcBFSFhMFrdKcQ50DKMo+x1gsPETNkUZCdwk1GhE/vyPArylLBOGwf
3fLb92SuwVwGq/ECoApUIJ5SEQAhTaWvL+LvlY3zpXTlmRtpc0rtHKO3QAB4wa9T
eVLPcCPEaC/UokEFVDBHg525A1/hYmvq2VElapCRDGJ20VvzSVlKmeHqmcgitwIu
e71X51AUlNk7KLBrbbSMU2dD/CO1hZOeH3tsaviTqAU7ZPe0yebooXPryEKn6+PN
x8bRKWpDRLCtqg9RngGRfi5gRnXvo6vpEVUnkwGGcll6W64uKYkDOiP2OyWG4mx5
pH59vf26UsZI5Xf4fOd74lyQsKXmAybJS6eU3AyxxONzE8/daqIpXbGpurE8Yq3P
PBfZNJk+TOyyQSOgWVT4+BYypm9GDeShMiLZsaD7owBgr3TK55UBZZXJxUiBt9dA
YGqgSs3S+8gdMx+prB3m
=g6qZ
-----END PGP SIGNATURE-----