[FFmpeg-devel] Embedded documentation?

[Nicolas George]

Stefano Sabatini (12023-05-08):
> Can you share more details about the plan? In particular, is the doc
> going to be embedded in the code itself (e.g. in the C
> implementation)? Or should we have some dedicated headers containing
> the docs?
> 
> We should also avoid to duplicate the same information between docs
> and code, so there should be some way to autogenerate the docs from
> the corresponding entries in the code.

This is far from settled, but I imagine something like that:

- Short doc paragraphs go directly in the C source code as comments with
  a specific markup, like doxygen but distinct from it.

- Longer doc texts go in a file with the same name as the C source code
  but a different extension, probably .md.

- The build system parses all this to generate source files with the
  structured documentation to be compiled into the library.

- The build system can also parse parts of the C source code to extract
  the structure information, for example AVOption initializers.

- The build system also parses the current texinfo documentation so that
  we do not have to rewrite it all at once.

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20230508/bcdc0543/attachment.sig>