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