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> --- As a side note, I actually find markdown much more pleasant to read and write than asciidoc. I think the output is not always as nice, as it does not have some of the structured elements that let us produce nice manpages, for example. But I wonder if it would be a better choice for formatting API documentation. Not something that is really relevant to this series, but just food for thought if we do end up with an extract+format tool. strbuf.h | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/strbuf.h b/strbuf.h index 8f63b38..078b805 100644 --- a/strbuf.h +++ b/strbuf.h @@ -33,10 +33,9 @@ * NOTE: It is OK to "play" with the buffer directly if you work it this * way: * - * ---- - * strbuf_grow(sb, SOME_SIZE); <1> - * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); - * ---- + * strbuf_grow(sb, SOME_SIZE); <1> + * strbuf_setlen(sb, sb->len + SOME_OTHER_SIZE); + * * <1> Here, the memory array starting at `sb->buf`, and of length * `strbuf_avail(sb)` is all yours, and you can be sure that * `strbuf_avail(sb)` is at least `SOME_SIZE`. @@ -261,9 +260,7 @@ extern void strbuf_add(struct strbuf *, const void *, size_t); * NOTE: This function will *always* be implemented as an inline or a macro * using strlen, meaning that this is efficient to write things like: * - * ---- - * strbuf_addstr(sb, "immediate string"); - * ---- + * strbuf_addstr(sb, "immediate string"); * */ static inline void strbuf_addstr(struct strbuf *sb, const char *s) -- 2.2.0.454.g7eca6b7 -- 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