bpf.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Stephen Kitt <steve@sk2.org>
To: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org, bpf@vger.kernel.org,
	linux-kernel@vger.kernel.org, linux-remoteproc@vger.kernel.org,
	linux-can@vger.kernel.org, linux-afs@lists.infradead.org,
	"Gustavo A . R . Silva" <gustavo@embeddedor.com>
Subject: Re: [PATCH] docs: use flexible array members, not zero-length
Date: Sat, 28 Sep 2019 10:55:57 +0200	[thread overview]
Message-ID: <20190928105557.221fb119@heffalump.sk2.org> (raw)
In-Reply-To: <20190928011639.7c983e77@lwn.net>

[-- Attachment #1: Type: text/plain, Size: 1751 bytes --]

On Sat, 28 Sep 2019 01:16:39 -0600, Jonathan Corbet <corbet@lwn.net> wrote:
> On Fri, 27 Sep 2019 16:29:27 +0200
> Stephen Kitt <steve@sk2.org> wrote:
> > diff --git a/Documentation/bpf/btf.rst b/Documentation/bpf/btf.rst
> > index 4d565d202ce3..24ce50fc1fc1 100644
> > --- a/Documentation/bpf/btf.rst
> > +++ b/Documentation/bpf/btf.rst
> > @@ -670,7 +670,7 @@ func_info for each specific ELF section.::
> >          __u32   sec_name_off; /* offset to section name */
> >          __u32   num_info;
> >          /* Followed by num_info * record_size number of bytes */
> > -        __u8    data[0];
> > +        __u8    data[];
> >       };  
> I only checked this one, but found what I had expected: the actual
> definition of this structure (found in tools/lib/bpf/libbpf_internal.h)
> says "data[0]".  We can't really make the documentation read the way we
> *wish* the source would be, we need to document reality.
> I'm pretty sure that most of the other examples will be the same.

Aargh, yes, of course, thanks for checking! I was locked in a “prescriptive”
documentation mode, but this type of documentation has to be descriptive
since it’s documenting shared structures, not structures which developers
have to write.

> If you really want to fix these, the right solution is to fix the offending
> structures — one patch per structure — in the source, then update the
> documentation to match the new reality.

Yes. I have a Coccinelle script which takes care of the code, but it doesn’t
work for docs ;-).

Wouldn’t it be better to update the docs simultaneously in each patch which
fixes a structure? Or is that unworkable with current development practices?



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

  reply	other threads:[~2019-09-28 12:34 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-27 14:29 [PATCH] docs: use flexible array members, not zero-length Stephen Kitt
2019-09-28  7:16 ` Jonathan Corbet
2019-09-28  8:55   ` Stephen Kitt [this message]
2019-09-30 17:00     ` Jonathan Corbet

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:

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

  git send-email \
    --in-reply-to=20190928105557.221fb119@heffalump.sk2.org \
    --to=steve@sk2.org \
    --cc=bpf@vger.kernel.org \
    --cc=corbet@lwn.net \
    --cc=gustavo@embeddedor.com \
    --cc=kvm@vger.kernel.org \
    --cc=linux-afs@lists.infradead.org \
    --cc=linux-can@vger.kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-remoteproc@vger.kernel.org \


* 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.
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 NNTP newsgroup(s).