Re: Question about intended behavior of 'insert-for-yank-1'.

[Karl Fogel]

Eli Zaretskii <address@hidden> writes:
>> Thanks, Eli.  Yes, that's true, but note that the doc string for
>> `insert-for-yank' just refers the reader to `insert-for-yank-1' for
>> details.  The only doc string where the STRING-passing behavior is
>> discussed is the doc string of `insert-for-yank-1', and that doc
>> string indicates, or strongly implies, that the entirety of STRING
>> is passed (which it isn't).
>
>Ah, so this is about the doc string of insert-for-yank, not its
>subroutine.

I think that's fair, yes.  It's about the combination of the two doc strings: 
right now, the `insert-for-yank' doc string just refers the reader to 
`insert-for-yank-1' for all the interesting stuff.  If your point is that 
solving this documentation bug involves changing the documentation of 
`insert-for-yank' more than that of `insert-for-yank-1' (and that the latter 
might not changing at all), that makes sense, and I thank you for pointing out 
the real source of the problem.

>I agree that the doc string of insert-for-yank should describe what it
>does.  What it says now hardly qualifies as documentation, and
>referring to an internal subroutine for that is, shall we say,
>suboptimal ;-)

Really, stepping back from the trees to see the forest, that should have been 
my first reaction :-).

>Feel free to improve the doc string of insert-for-yank.

Will do.

While I don't see any outright errors in the doc string of `insert-for-yank-1', 
IMHO it should more clearly document that STRING is the default argument to 
FUNCTION, so I may also fix that.

Thanks, Eli.

-Karl