[Doc-SIG] Re: docstring signatures

[Greg Ward]

On 24 March 2001, Guido van Rossum said:
> It should be easier to combine code and documentation for 3rd party
> modules, and there should be an easier way to integrate such
> documentation into (a version of) the standard documentation.  But I
> disagree with the viewpoint that documentation should be maintained in
> the same file as source code.  (If you believe the argument that it
> is easier to ensure that it stays up to date, think again.  This never
> worked for comments.)

>From direct personal experience (15 or so Perl modules, some on CPAN and
some not, comprising ~10k LoC), I *do* think that intermingling code and
documentation makes it easier to update them together.

Note that it does not make it *absolutely* easy or painless or automatic;
any of those are bogus arguments.  But having code and doccs in the same
file definitely makes life *less* painful.

        Greg