On Sat, 28 Sep 2019 01:16:39 -0600, Jonathan Corbet <corbet@xxxxxxx> wrote: > On Fri, 27 Sep 2019 16:29:27 +0200 > Stephen Kitt <steve@xxxxxxx> 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
Attachment:
pgp6LikYIb8Og.pgp
Description: OpenPGP digital signature
