[FFmpeg-user] "documented implicitly" [was: Re: Why is format=rgb24 required after maskedmerge?]

[Jim DeLaHunt]

On 2020-08-19 07:34, Paul B Mahol wrote:
> You are deeply confused about our filters.
> Any filter can change pixel formats to one that they accepts thus gbrp
> is picked instead of packed rgb, this is already documented
> implicitly.

Wow, "documented implicitly". This is such a classic FFmpeg project 
statement. The role of documentation is to explain, explicitly, at a 
suitable level of detail. What does "documented implicitly" even mean?

I think this thread points out is that FFmpeg documentation is 
inadequate. It is hard to prove a negative, but I suspect that the term 
"pixel format" is not actually defined in the FFmpeg documentation. I 
suspect that the statement, "Any filter can change pixel formats" is not 
stated either. Certainly the maskedmerge filter documentation[1] doesn't 
mention pixel formats at all, much less say what pixel formats the 
filter sets for its output.

I have attempted to improve the documentation, to make it explain 
explicitly instead of fail to document. I encountered a great deal of 
resistance to those patches, because they make the documentation more 
explicit, because they have more words, and because documentation has so 
little value in this project relative to executable code.

And yet "You are deeply confused about our filters". In other words, the 
documentation has failed to explain to you what FFmpeg does, the project 
has failed to write or welcome improved documentation, you do not 
understand how FFmpeg works — and somehow this is your fault.

[1] http://ffmpeg.org/ffmpeg-all.html#maskedmerge