[Doc-SIG] docstring grammar

[M.-A. Lemburg]

"Fred L. Drake, Jr." wrote:
> 
> M.-A. Lemburg writes:
>  > Perhaps there is a way to only extract class/function/method
>  > __doc__ strings from pyc-modules without actually running them,
>  > since those are really our only targets.
> 
>   I look forward to your software.  ;-)

Ahh, yes... well... perhaps someday ;-) right now I'm busy with
other things which go one level deeper, namely the Unicode
intergration.

>   But see also my response to Paul's message about documenting
> extension modules.

About the add-on Python module with included doc strings... well,
I don't think that's easily possible since function objects
are immutable AFAIK (and these contain the doc strings). Also
separating the docs and the implementation too far is not
very convenient, e.g. I use C macros to help me with this:

Py_C_Function( mxDateTime_now,
	       "now()\n\n"
	       "Returns a DateTime-object reflecting the current local time."
	       )
{
...
}

I have to add that I maintain my package docs as a completely
separate entities: experience has it that leaving things undocumented
for a while is better if you work on new things in already pretty
wide spread tools such as mxDateTime. Also, the details you
want to include in the "real" docs sometimes don't make sense
within the code or simply don't fit anywhere.

-- 
Marc-Andre Lemburg
______________________________________________________________________
Y2000:                                                    28 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/