[Doc-SIG] Re: Doc-SIG digest, Vol 1 #301 - 11 msgs

[Edward D. Loper]

> >> Are we expecting people to *want* to link into a document from
> >> outside?  I can't see ever having any use for that when writing
> >> API docs...
> > 
> > I don't have a use for it, myself, directly.
>
> erm.  The documentation of class Foo overrides a method of Foo's base,
> explains the difference in Foo's version's docstring, but needs to refer
> to the bit of the base's implementation in which is explained the
> hideous and hairy reason why certain bits have to behave the way they
> do.  The base's implementation's docstring gave that portion a named
> anchor to which derived classes' docstrings could refer.

It seems to me that this is asking for broken pointers, etc., within
our docs, the next time someone updates the base implementation's
docs..  API doc strings really shouldn't be that long anyway, so I
don't feel so bad about referring someone to an entire docstring..

-Edward