[libav-api] [RFC] doxy for internal API

Nathan nathan.stocks at gmail.com
Wed Aug 1 19:19:03 CEST 2012


On Wed, Aug 1, 2012 at 5:48 AM,  <anton at khirnov.net> wrote:
>
> Hi,
> I have a disagreement with Diego about generating doxygen docs.
>
> Currently we generate doxygen for all files in Libav, which IMO leads to
> horribly cluttered output.
> See e.g.
> https://libav.org/doxygen/master/files.html
> https://libav.org/doxygen/master/annotated.html
> https://libav.org/doxygen/master/classes.html
> https://libav.org/doxygen/master/globals_func.html
> A mountain of stuff that's absolutely useless to people who want public
> API documentation. It just makes searching for what they need much
> harder.
>
> For this reason I think we should only generate doxy for installed
> headers, so the output contains only public API documentation.
> At least that should be the default, we can have a second alternative
> doxy config file that would generate docs for everything.
>
> OTOH Diego claims we should keep generating doxy for all files. I'm sure
> he'll present his reasons and arguments himself.
>
> If there indeed are people who read generated doxy for non-public API,
> I'd like them to speak up and prove their existence.
> Everyone else with an opinion is of course welcome to comment as well.

As someone only using the public API, only documenting the public API
would better suit my purposes.  Playing devil's advocate, though,
couldn't _both_ sets of documentation be produced, and simply label
one 'public API documentation' and label the other one 'public &
private API documentation' -- or something like that?  I'll survive in
whatever case.

~ Nathan


More information about the libav-api mailing list