[FFmpeg-user] Some more thoughts on documentation

[Phil Rhodes]

 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. 
That tends to be true for, say, one function, or a few functions. And sure, OK, if you want to spend a lot of time scanning around in potentially several source files, you can work things out, though it's longwinded.
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
P