Re: [PATCH/RFC] doc: document error handling functions and conventions (Re: [PATCH 03/14] copy_fd: pass error message back through a strbuf)

[Michael Haggerty <mhagger@alum.mit.edu>]

On 02/13/2015 12:08 AM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
>> Jeff King <peff@peff.net> writes:
>>
>>> On Fri, Dec 05, 2014 at 10:00:05AM -0800, Junio C Hamano wrote:
>>>
>>>> I am more worried about variable length part pushing the information
>>>> that is given later out to the right, e.g. "error: missing file '%s'
>>>> prevents us from doing X".  Chomping to [1024] is not a good
>>>> strategy for that kind of message; abbreviating %s to /path/name/...
>>>> (again, with literally "...") would be.
> 
> I have this one in my pile of Undecided topics:
> 
>     * jn/doc-api-errors (2014-12-04) 1 commit
>      - doc: document error handling functions and conventions
> 
>      For discussion.
>      What's the status of this one????
> 
> I think we all agree that the early part of the new documentation
> text is good, but the last section that proposes to store more
> detailed errors in caller supplied strbuf in textual form was
> controversial (and I have not convinced myself it is a good idea
> yet).
> 
> I could chuck the last section and then start merging the remainder
> to 'next' to salvage the "obviously good bits".  Or do people want
> to hash its last section a bit more?

Whether or not we decide on a different error-handling convention in the
future, it is a fact of life that a good bit of code already uses the
"strbuf" convention documented by Jonathan's patch. So I think it is OK
to merge it as is. If we change the preferred convention in the future,
one part of the change will be to update this file.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu