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
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
