On 2020-08-14 11:34 +0200, Jean-Baptiste Kempf wrote:
> On Wed, 12 Aug 2020, at 14:38, Alexander Strasser wrote:
> > 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.
>
> SHOULD can mean "really mandatory, besides exceptions", so I would soften it,
> to explain common sense must be shared, like "if origin is mathematical or
> specification", or similar.
>
> But I like your version.
Maybe instead of
Definitions of non-obvious data should have a short comment
explaining their origin.
changing the first paragraph to
Consider documenting the origin of non-obvious data in a
short commment above its definition.
would help?
It sounds less like a "formal should" and probably doesn't change the
"effective adoption rate" at all. What do you think?
Thanks for your feedback!
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".
