[FFmpeg-devel] Documentation: proposed changes in the structure

[Michael Niedermayer]

On Sat, Aug 22, 2020 at 02:12:13PM +0200, Nicolas George wrote:
> Clement Boesch (12020-08-22):
> > AVOption.help and AVFilter.description (as well as AVCodec.description
> > etc) do contain redundant information with the documentation.
> 
> There is truth in what you say, but I disagree this is really redundant:
> AVOption.help and AV*.description are supposed to be very short, while
> the text in the documentation is supposed to be descriptive, with
> explanations.
> 
> > Additionally, we sometimes document manually the default, all the
> > constants, sometimes the ranges, which are already held within the
> > AVOption.
> 
> I agree, the default value and constants can, to an extents, be
> generated automatically.
> 
> > So yes I'd rather have the AVOption.help extended to contain more and have
> > a tool which is basically `ffmpeg -h filter=xxx` in the choosen markup.
> 
> This is exactly what we are talking about, except for two details:
> 
> - We cannot extend AVOption.help without causing an ABI and API break,
>   but we can create a new more generic system and keep .help only as a
>   small supplement and for compatibility.

iam not sure what extension you (plural) envission here but AVOption.help
can be extended without breaking API/ABI.
Consider if for example one wanted to add a filename, markdown or other
text string. AVOption.help is a zero terminated string. you can add
something after the 0 like a 2nd zero terminated string.
to know if that is there a flag can be added to the AVOption.flags
or AVClass.version can be used.

thx

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

Avoid a single point of failure, be that a person or equipment.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20200822/d332d230/attachment.sig>