[Doc-SIG] Re: docstring signatures
Mon, 26 Mar 2001 09:39:06 -0500
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.