[FFmpeg-user] Some more thoughts on documentation

[Mark Filipak]

On 08/23/2020 04:27 PM, Carl Zwanzig wrote:
> 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.

That leaves me out. It's also not true even for 'C' programmers for many reasons involving poor 
choices of variable names, undocumented structures, strange methods, misunderstandings, etc., but I 
don't want to get into a debate. I'd rather submit some of what I've already done and see what folks 
think.

In other words, I'd rather do documentation than talk about documentation. Let's decide what works 
as we go, eh?

How do we start? Should I post stuff to this list? Or is there another, better way?

> 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

That's written in Martian. I don't read Martian.

> https://ffmpeg.org/developer.html#toc-Code-of-conduct

"Kumbaya". It's pertinence to writing documentation is what?

> However that doesn't directly affect the user documentation.

Agreed.

- Mark.