git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Stefan Beller" <sbeller@google.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
	git <git@vger.kernel.org>
Subject: Re: [PATCH 1/8] sha1-array: provide oid_array_filter
Date: Wed, 26 Sep 2018 16:51:48 -0400	[thread overview]
Message-ID: <20180926205148.GA12340@sigill.intra.peff.net> (raw)
In-Reply-To: <xmqqpnx0j9kn.fsf@gitster-ct.c.googlers.com>

On Wed, Sep 26, 2018 at 01:19:20PM -0700, Junio C Hamano wrote:

> >     /**
> >     Would we be open to consider another commenting style?
> 
> No.  You still cannot write */ in that comment section, for example,
> so you cannot do "plain text" still---that is not a great trade off
> to deviate from the common comment style used for other stuff.

We can do:

#if HEADER_DOC

Write anything here except #endif!

#endif /* HEADER_DOC */

But I actually think that is more jarring than a big comment (when I am
reading C code, I expect to see C-like things mostly.

I do agree with you that a true plain text file is nicer in terms of
freedom to format, etc. But IMHO the tradeoff is easily worth it to keep
the related content (function declarations and their documentation)
close together.

-Peff

  reply	other threads:[~2018-09-26 20:51 UTC|newest]

Thread overview: 51+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-09-21 22:35 [PATCHv3 0/8] fetch: make sure submodule oids are fetched Stefan Beller
2018-09-21 22:35 ` [PATCH 1/8] sha1-array: provide oid_array_filter Stefan Beller
2018-09-22 12:58   ` Ævar Arnfjörð Bjarmason
2018-09-25 19:26     ` Stefan Beller
2018-09-26  4:15       ` Jeff King
2018-09-26 17:10         ` Junio C Hamano
2018-09-26 17:49           ` Ævar Arnfjörð Bjarmason
2018-09-26 18:27             ` Junio C Hamano
2018-09-26 18:34               ` Jeff King
2018-09-26 18:43               ` Ævar Arnfjörð Bjarmason
2018-09-26 18:58                 ` Jeff King
2018-09-26 19:39                   ` Stefan Beller
2018-09-26 19:49                   ` Junio C Hamano
2018-09-26 19:59                     ` Stefan Beller
2018-09-26 20:19                       ` Junio C Hamano
2018-09-26 20:51                         ` Jeff King [this message]
2018-09-26 21:22                         ` Stefan Beller
2018-09-26 20:44                   ` On shipping more of our technical docs as manpages Ævar Arnfjörð Bjarmason
2018-09-26 21:40                     ` Junio C Hamano
2018-09-26 23:21                     ` Stefan Beller
2018-09-27  8:58                       ` Ævar Arnfjörð Bjarmason
2018-09-27  6:20                     ` Jeff King
2018-09-27  6:34                       ` Jonathan Nieder
2018-09-27  6:40                         ` Jeff King
2018-09-27 17:36                       ` Junio C Hamano
2018-09-27 18:25                         ` Jeff King
2018-09-27 21:27                         ` [PATCH] Documentation/CodingGuidelines: How to document new APIs Stefan Beller
2018-09-27 21:43                           ` Junio C Hamano
2018-09-27 22:21                             ` Ævar Arnfjörð Bjarmason
2018-09-27 23:27                           ` Jonathan Nieder
2018-09-28  1:11                             ` Jeff King
2018-09-28 16:50                               ` Junio C Hamano
2018-09-28 17:30                                 ` [PATCH] strbuf.h: format according to coding guidelines Stefan Beller
2018-09-28 19:54                                   ` Junio C Hamano
2018-09-28 20:11                                     ` Junio C Hamano
2018-09-28 21:38                                       ` Junio C Hamano
2018-09-29  7:38                                       ` Jeff King
2018-09-28 21:42                                   ` Junio C Hamano
2018-09-28 21:54                                     ` Stefan Beller
2018-09-28 19:47                                 ` [PATCH] Documentation/CodingGuidelines: How to document new APIs Martin Ågren
2018-09-29  7:46                                 ` Jeff King
2018-09-28 17:14                               ` Stefan Beller
2018-09-29  7:41                                 ` Jeff King
2018-09-27  6:48                   ` [PATCH 1/8] sha1-array: provide oid_array_filter Jeff King
2018-09-21 22:35 ` [PATCH 2/8] submodule.c: fix indentation Stefan Beller
2018-09-21 22:35 ` [PATCH 3/8] submodule.c: sort changed_submodule_names before searching it Stefan Beller
2018-09-21 22:35 ` [PATCH 4/8] submodule: move global changed_submodule_names into fetch submodule struct Stefan Beller
2018-09-21 22:35 ` [PATCH 5/8] submodule.c: do not copy around submodule list Stefan Beller
2018-09-21 22:35 ` [PATCH 6/8] submodule: fetch in submodules git directory instead of in worktree Stefan Beller
2018-09-21 22:35 ` [PATCH 7/8] fetch: retry fetching submodules if needed objects were not fetched Stefan Beller
2018-09-21 22:35 ` [PATCH 8/8] builtin/fetch: check for submodule updates for non branch fetches Stefan Beller

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20180926205148.GA12340@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=sbeller@google.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).