On 12/12/2014 11:39 PM, Jonathan Nieder wrote:
> Jeff King wrote:
>
>> This is much easier to read when the whole thing is stuffed
>> inside a comment block. And there is precedent for this
>> convention in markdown (and just in general ascii text).
>>
>> Signed-off-by: Jeff King <peff@xxxxxxxx>
>> ---
>
> Reviewed-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
>
>> As a side note, I actually find markdown much more pleasant to read and
>> write than asciidoc.
>
> I do, too. Quoting in asciidoc is a nightmare.
Peff, thanks for working on this. I think it is a definite improvement.
I suggest that we accept the use of asciidoc/markdown's convention of
using backwards quotes to mark code snippets (especially identifier
names) within comments *anywhere* in our code base. For example, this
appears in refs.c:
/*
* Create a struct ref_entry object for the specified dirname.
* dirname is the name of the directory with a trailing slash
* (e.g., "refs/heads/") or "" for the top-level directory.
*/
I claim that it is more readable with a tiny bit of markup:
/*
* Create a `struct ref_entry` object for the specified `dirname`.
* `dirname` is the name of the directory with a trailing slash
* (e.g., "refs/heads/") or "" for the top-level directory.
*/
Marking up `struct ref_entry` helps make it clear that the two words
belong together, and marking up `dirname` makes it clear that we are
talking about a specific identifier (in this case, a function parameter).
Currently, comments use a mix of unadorned text, single-quoted text, and
double-quoted text when talking about code. I think the
asciidoc/markdown convention is clearer [1].
I think we shouldn't be pedantic about this. When a comment is readable
with no markup, there's no need to add markup. And "incorrect" markup
shouldn't by itself be reason to reject a patch. But in many examples, a
little bit of markup makes the text less ambiguous and easier to read.
Michael
[1] Yes, I see the irony in trying to improve a mixture of three
conventions by adding a fourth one.
--
Michael Haggerty
mhagger@xxxxxxxxxxxx
--
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