Re: [PATCH v3/GSoC 2/5] path.c: implement xdg_runtime_dir()

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 25, 2016, 18:00 UTC
Message-ID: <xmqq4mbu4evm.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <20160325175510.GA10563@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 18 quoted lines

>> > That's clearer, but if I were the caller, I would worry about the
>> > security of the path.
>> > How about adding:
>> >
>> > The security of the path is ensured by file permission.
>> 
>> Is "by file permission" descriptive enough?
>> 
>> To protect /a/b/c/socket, what filesystem entities have the right
>> permission bits set?  If the parent directory is writable by an
>> attacker, the permission bits on 'socket' itself may not matter as
>> the attacker can rename it away and create new one herself, for
>> example.
>
> I think that is discussed elsewhere, and referring to the xdg document
> is enough. My main point is that the docstring about a function should
> tell a potential caller what they need to know to use it, but if it gets
> overly long, that information is lost in the noise.

I agree with your main point, and I was wondering if "by file permission" is merely adding yet another noise if there is discussion elsewhere already, and/or if it does not refer to an external document that has a fuller discussion, because it lacks any useful information by itself.