From: Junio C Hamano Date: Fri, 25 Mar 2016 18:00:13 GMT Subject: Re: [PATCH v3/GSoC 2/5] path.c: implement xdg_runtime_dir() Message-ID: In-Reply-To: <20160325175510.GA10563@sigill.intra.peff.net> Jeff King writes: >> > 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.