On Fri, Mar 25, 2016 at 09:55:59AM -0700, Junio C Hamano wrote: > 惠轶群 <huiyiqun@xxxxxxxxx> writes: > > >> There's a lot of "what" here that the caller doesn't really care about, > >> and which may go stale with respect to the implementation over time. Can > >> we make something more succinct like: > >> > >> /* > >> * Return a path suitable for writing run-time files related to git, > >> * or NULL if no such path can be established. The resulting string > >> * should be freed by the caller. > >> */ > >> > >> ? > > > > 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. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html