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

[Alexander Strasser]

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.

I just dropped the explicit mention, since I feel it added no value.
There were some comments in this discussion, indicating to me that
it could even irritate more than help.

Do you think mentioning RE explicitly would be better? If yes, why?

For RE there are theoretically different ways to gain values,
if it was reconstructed by inspecting and comparing outputs of
a binary, that methods could be described or sources of the used
tools could be included.

If it is just a dump of a table from a binary or a trivial
transformation thereof, than adding a comment might not have much
value at all. Maybe if a contributor is comfortable with it, he
could mention from which binary it was dumped. In some cases
it might not really be different at all from a pointer to a spec,
if the spec doesn't reveal the origin of the included data.

If the dump has undergone non-obvious transformations, then
describing those would certainly be helpful.

As Nicolas mentioned before, for such special cases discussions
could happen on an case by case basis if a reviewer cares enough.

As I cannot judge any legal stuff surrounding this, which could
even be different in different countries, I guess it's important
to not urge individuals to write things they are not comfortable
with.


  Alexander