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

[Alexander Strasser]

Hi Nicolas!

Am 8. August 2020 23:26:02 MESZ schrieb Mark Thompson <sw at jkqxz.net>:
>On 08/08/2020 18:57, Nicolas George wrote:

[...]

>> Andreas:

I'm sure the following was addressed at me.


>>> 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.

Yes, that's fine.

IMHO we don't actually need ideology for this matter.


>>> wording of the patch.
>> 
>> Have you suggestions to make it better?

At least the aspect Mark mentioned below.

In general I think it could be worded a bit clearer and easier to grasp. Basically it should ask for a short comment in front of non-obvious data definitions.

I can try to write something later or tomorrow. Not sure if I can really come up with something much better, so I would be OK with your wording if Mark's comment is addresed.


  Alexander

>>> 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