[FFmpeg-user] Some more thoughts on documentation

[Carl Zwanzig]

On 8/23/2020 12:30 PM, Mark Filipak wrote:
> Developer preparation: Kindly add comments to the source code. The comments 
> don't need to teach or explain. They just need to repeat the code's logic, 
> but in English instead of Martian.

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. OTOH, there will be some 
cases they -do- need to be explained; there are always points in code which 
aren't obvious to the casual reader - could be some obscure part of the 
encoding, could be that it fails on some architectures but not on others, 
could be that a certain flag isn't appropriate, etc. But in general, most 
code out there isn't well commented, anyway. (Way back when, code wasn't 
considered well-commented if less than maybe 20-25% of the non-blank lines 
were comments.)

See also
https://ffmpeg.org/developer.html#Comments and
https://ffmpeg.org/developer.html#toc-Code-of-conduct

However that doesn't directly affect the user documentation.

Later,

z!