Messages in this thread | | | Date | Sat, 28 Sep 2019 10:55:57 +0200 | From | Stephen Kitt <> | Subject | Re: [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] | |