[FFmpeg-user] Some more thoughts on documentation
phil_rhodes at rocketmail.com
Mon Aug 24 12:11:44 EEST 2020
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
More information about the ffmpeg-user