[FFmpeg-user] Some more thoughts on documentation
list+ffmpeg-user at jdlh.com
Mon Aug 24 21:27:54 EEST 2020
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
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.
More information about the ffmpeg-user