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

[Alexander Strasser]

On 2020-08-09 13:13 +0200, Nicolas George wrote:
> Alexander Strasser (12020-08-09):
> > >> Andreas:
[...]
>
> > 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.
>
> Thanks. I will wait for your proposal, and in the meantime see if I can
> come up with a better way of saying it myself.

I ended up with this:

    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.

Not sure it's clearly better than your patch. It's different
and a bit longer and also includes the document section stuff.
As it splits the rule itself from the hints makes it's easier
to extract the essence.

As for the example, I couldn't readily find a good one in our
code base. So if anyone could point one out, that would help.
We could also use one of your examples, or we could leave out
the example entirely. I think it would be better to include one,
because it might raise adoption of the convention.

Anyway, use my words above as you see fit. If others agree
to this version, I can also sent a proper patch.


  Alexander