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

[Jean-Baptiste Kempf]

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.

-- 
Jean-Baptiste Kempf -  President
+33 672 704 734