lkml.org 
[lkml]   [2019]   [Sep]   [28]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] docs: use flexible array members, not zero-length
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?

Regards,

Stephen
[unhandled content-type:application/pgp-signature]
\
 
 \ /
  Last update: 2019-09-28 14:34    [W:0.055 / U:0.360 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site