[Doc-SIG] Allowing different docstring formats

Guido van Rossum guido@digicool.com
Fri, 30 Mar 2001 09:04:54 -0500

> What is your opinion on a "format" marker somewhere near the head of a 
> module, to allow for different and pluggable markup parsers (and/or 
> different versions of the same markup)?
> I see 3 options:
> 1. a comment like "#pragma docformat STNG" (yes, I'm a C++ guy, too ;)
> 2. a similar marker at the end of the module docstring
> 3. a special module variable __docformat__ (which has a default if it's 
> absent, namely the format used for standard library modules).
> The 1st has the distinct disadvantage that it's not available to 
> importers of the module. The 2nd is bad because we have to intrude the 
> very thing that we describe the format of. So personally, I prefer the 
> 3rd option. Anyone sees any problems with that one?

Sounds good to me.

--Guido van Rossum (home page: http://www.python.org/~guido/)