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

[Paul B Mahol]

On 8/20/20, Mark Filipak <markfilipak.windows+ffmpeg at gmail.com> wrote:
> On 08/19/2020 01:43 PM, Jim DeLaHunt wrote:
>> 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
>
> I have a theory, Jim. I think the developers don't document things (or
> comment their code) for 2
> reasons: 1, They want to be able to change methods and behaviors without
> having to maintain
> documentation, and 2, They want to make money doing consulting jobs for
> people who commit ffmpeg for
> their projects, then give up trying to write ffmpeg command lines.

Your both theories are fully correct. They want to make money for living.