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

[Mark Thompson]

On 08/08/2020 18:57, Nicolas George wrote:
> Tables that were not just written by the code author are
> not actually source code, otherwise,
> "recode data..x1 < proprietary.o > source.c"
> would be enough to launder a proprietary blob into
> the source code.
> 
> Documenting the origin of the tables or the methods
> for their generation is necessary to let other developers
> take over if the original author is no longer available.
> 
> Signed-off-by: Nicolas George <george at nsup.org>
> ---
>   doc/developer.texi | 8 ++++++++
>   1 file changed, 8 insertions(+)
> 
> 
> I count:
> 
> - Two objections, to which I have answered, and who have not given
>    follow up.
> 
> - One objection about a typo, I fixed "engineered" and proof-read
>    everything carefully.
> 
> - Two positive opinions.

+1 from me too, I think this is a good thing to include.

> 
> Andreas:
> 
>> Not sure I agree with your definition of Libre Software and your exact
> 
> I was more trying to express the difference between Libre Software and
> Open Source, which is minute in legal terms but huge in terms of
> mentality. Anyway, this part is only explanatory, it does not go into
> the tree.
> 
>> wording of the patch.
> 
> Have you suggestions to make it better?
> 
>> I agree that leaving a hint of where the data comes from, directly where
>> the data is defined in the source code, is a good thing and probably not
>> to much to ask for.
> 
> Thanks.
> 
> 
> diff --git a/doc/developer.texi b/doc/developer.texi
> index b33cab0fc7..c3103f31dc 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -216,6 +216,14 @@ please use av_log() instead.
>   @item
>   Casts should be used only when necessary. Unneeded parentheses
>   should also be avoided if they don't make the code easier to understand.
> +
> + at item
> +If the code contains tables of numbers or other data, their origin should be
> +documented in a comment, so that other developers can rebuild them if
> +necessary. If they were taken from a reference, include the URL of that
> +reference. If they were computed by a tool, include the code of the tool.
> +If they were reverse-engineered, include an honest attempt at explaining the
> +methods used.

Also: if they were taken from a written specification, include the section or table number within that specification.

(A reference to "H.264 table A-1" is more useful than one to "<https://www.itu.int/rec/T-REC-H.264/en>".)

>   @end itemize
>   
>   @section Editor configuration
> 

Thanks,

- Mark