> -----Original Message----- > From: Alexei Starovoitov <alexei.starovoitov@xxxxxxxxx> > Sent: Tuesday, October 4, 2022 9:20 AM > To: Dave Thaler <dthaler@xxxxxxxxxxxxx> > Cc: bpf@xxxxxxxxxxxxxxx > Subject: Re: [PATCH 11/15] ebpf-docs: Improve English readability > > On Tue, Oct 4, 2022 at 8:56 AM Dave Thaler <dthaler@xxxxxxxxxxxxx> > wrote: > > > > Also worth noting that Quentin has a script that I believe parses the > > appendix and uses it to generate a validator for ebpf programs. > > (Which also helps validate the appendix). > > The last thing I want to see is a document becoming a description of the > code. > We've always been doing it the other way around. > The documentation can live next to the code and docs automatically > generated from .h or .c files. > Doing the other way around sooner or later will be a disaster. > Imagine a typo in instruction-set.rst. > What should we do next? Fix a typo and say, look, the code behaves > differently, so we're fixing the doc. > If so, there is close to zero reason to add hex to the doc, since it's not an > authoritative answer. > On the other hand if instruction-set.rst is the source of the truth then the > code would have to change, which we obviously cannot do. So let's not get us > into the corner with such tables. The point of a standard is to be a source of truth. If another implementation (ubpf, hbpf, etc.) doesn't match the spec, then the code would have to change. Such tables are seen as invaluable for determining correctness of other implementations. So the feedback is that it's important to have such if we want everyone else to do the right thing. > These people should speak up then. I agree. Dave
