[FFmpeg-devel] [PATCH v2] doc/developer: origin of tables should be documented.

[Alexander Strasser]

On 2020-08-14 11:34 +0200, Jean-Baptiste Kempf wrote:
> On Wed, 12 Aug 2020, at 14:38, Alexander Strasser wrote:
> > On 2020-08-12 12:32 +0200, Jean-Baptiste Kempf wrote:
> > > On Wed, 12 Aug 2020, at 00:29, Alexander Strasser wrote:
> > > >     Definitions of non-obvious data should have a short comment
> > > >     explaining their origin.
> > > >
> > > >     If the data is of mathematical origin, you can document that
> > > >     or use code snippets or pseudo-code. If the data was gained
> > > >     empirically, describe the methods used. If the data was taken
> > > >     from a document like a specification, reference the section
> > > >     and/or table number. A link can also be used, if there is a
> > > >     stable source and there are no better ways.
> > > >
> > > >     If you generated the data with a program, consider including
> > > >     the source code in FFmpeg and reference it in the comment.
> > > >
> > > >     Typical examples are tables of numbers. Here is one:
> > > >
> > > >         <nice example to be found and inserted>
> > > >
> > > >
> > > > I feel it could well be improved, though I wasn't able to do it
> > > > myself :( Maybe others can help.
> > >
> > > What about RE values?
> >
> > All in all it's same as Nicolas' proposal: The convention is to
> > document the origin of the data. It says should, which is not must.
>
> SHOULD can mean "really mandatory, besides exceptions", so I would soften it, to explain common sense must be shared, like "if origin is mathematical or specification", or similar.
>
> But I like your version.

Maybe instead of

    Definitions of non-obvious data should have a short comment
    explaining their origin.

changing the first paragraph to

    Consider documenting the origin of non-obvious data in a
    short commment above its definition.

would help?

It sounds less like a "formal should" and probably doesn't change the
"effective adoption rate" at all. What do you think?

Thanks for your feedback!


  Alexander