[FFmpeg-user] Some more thoughts on documentation

[Jim DeLaHunt]

On 2020-08-24 02:11, Phil Rhodes via ffmpeg-user wrote:

>   On Sunday, 23 August 2020, 21:27:17 BST, Carl Zwanzig <cpz at tuunq.com> wrote:
>   
>> I think we'll have to disagree on that, most of the basic logic should be
>> fairly clear to someone who knows the 'c' language.
> …There should always be a narrative description, as short as possible but no shorter, of how a chunk of the code is intended to be used and what the general control flow is. The definition of "chunk" in this context is a matter of opinion, but a general overview of the intent of the code is a massive time-saver. Examples help, but a narrative description is hugely helpful, especially to people who are new to the situation.
> No, "read the source" is not an answer to this, and neither is doxygen. Doxygen tells you what individual functions do. It doesn't generally tell you what the whole thing does.
> Microsoft do this sort of thing incredibly well: https://docs.microsoft.com/en-us/windows/win32/directshow/how-to-play-a-file


I agree about the value of narrative descriptions.  For instance, in 
reading the DirectShow "How to Play a File" article, I think of how very 
helpful it would be to have a narrative description of "How FFmpeg calls 
a video filter", which describes the entry points to a filter and when 
FFmpeg calls them and what the filter is supposed to do in response. 
Also, each filter would benefit from a narrative description of what the 
author intends the filter to do, and how to use it within an FFmepg 
invocation.

FFmpeg is a large and complex system. It is worth thinking of it as a 
standard library, or an OS, when planning what documentation is useful. 
Don't think of it as a single function or as a small standalone program.