Clement Boesch (12020-08-22): > AVOption.help and AVFilter.description (as well as AVCodec.description > etc) do contain redundant information with the documentation.
There is truth in what you say, but I disagree this is really redundant: AVOption.help and AV*.description are supposed to be very short, while the text in the documentation is supposed to be descriptive, with explanations. > Additionally, we sometimes document manually the default, all the > constants, sometimes the ranges, which are already held within the > AVOption. I agree, the default value and constants can, to an extents, be generated automatically. > So yes I'd rather have the AVOption.help extended to contain more and have > a tool which is basically `ffmpeg -h filter=xxx` in the choosen markup. This is exactly what we are talking about, except for two details: - We cannot extend AVOption.help without causing an ABI and API break, but we can create a new more generic system and keep .help only as a small supplement and for compatibility. - C source files are not the place for lengthy text. > I meant the other way around: you have a gen-doc.c which you compile and > link against the library, which generates the .md (integration within the > make is easy). If the documentation is embedded in the library, then clearly there sould be an API to present it. And we could use it to build the static documentation. It would not work for cross-compilation, though. Another option is to have a FATE tests that checks the consistency of the documentation with the options. I think this better, because although redundancy without check leads to inconsistency, redundancy with checks helps make sure we write what we mean and we mean what we write. > But I think we have it wrong with the documentation approach. What is > currently described within the code corresponds to the "technical > documentation". While all the extra information on the filters may enter > within the "explanation" and "tutorial" realm. This means that we could > have a filter documentation that starts with the technical documentation > (generated from the code) followed by all the "extra" detailed info on the > filter themselves. > > It might get clumsy but at least we wouldn't have to paraphrase with a > different formatting every single option, and miss half of them on a > regular basis. > > You may want to read https://documentation.divio.com/ to understand better > the separation I'm making. I read "simple and comprehensive", I automatically translate "oversimplification". The distinction between reference and explanations on one side and tutorials and how-to guides on the other side makes sense. On the other hand, there is a continuum between tutorials and how-tos, and a continuum between reference and explanations. > To clarify just a little here: the non technical documentation would be > written manually outside of the code, just like currently (except we would > strip out all the redundant info with the tech doc). The documentation for components, which is the bulk of the documentation and what we are discussing now, is "reference", with just enough of "explanation" to make it self-contained without overlapping with transverse documentation. I agree that it belongs with each component. But again, a C source file is not the place for this, mixing syntaxes is rarely a good idea. Which is exactly why I suggest to have a parallel structure $lib/$component.c + $lib/doc/$component.md. Regards, -- Nicolas George
signature.asc
Description: PGP signature
_______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org https://ffmpeg.org/mailman/listinfo/ffmpeg-devel To unsubscribe, visit link above, or email ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
