On 2020-08-24 02:11, Phil Rhodes via ffmpeg-user wrote:
On Sunday, 23 August 2020, 21:27:17 BST, Carl Zwanzig <c...@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.
_______________________________________________
ffmpeg-user mailing list
ffmpeg-user@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-user
To unsubscribe, visit link above, or email
ffmpeg-user-requ...@ffmpeg.org with subject "unsubscribe".
