[OE-core] [PATCH 2/2] Add api-doc class

[Burton, Ross]

On 19 May 2014 04:18, Zongchun YU <b40527 at freescale.com> wrote:
>>It's not opt-in: once a recipe is using doxygen.bbclass then it has a build dependency on doxygen-native and *will* generate documentation.
>>This is needless overhead if you don't intend to read the documentation.
>
> I think if you intend to read the documentation. Just inherit this class. If not. there is no need to inherit this class.

So you're suggesting that if a user wants documentation generated they
should know what recipes they can add "inherit api-doc" to?

I'll repeat my proposal: every recipe that can generate doxygen
documentation inherits a doxygen class, and that class can look at a
distro-level variable along the likes of GENERATE_API_DOCS (which a
hypothetical non-stub gtk-doc class can also respect).

>>You can't assert that the documentation is solely generated on the shipped files in the tarballs: what if some of the files are machine-generated?  Or if with for example DBus, the doxygen is generated?
>>I've nothing against a doxygen class and would like to also see a gtk-doc class that isn't a stub, with a single distribution-level "generate API documentation" variable controlling them.  But the documentation has to be generated at build time, and I think it's fair to assume that is a package has API documentation then "make" will build it, otherwise the method to build the documentation will be different for every package.
>>For example, DBus has a Doxyfile.in at the top of the source tree, so not only does configure needs to run to generate a Doxyfile but that Doxyfile is written to ${B}, not ${S}.
>
> OK. You are right. What about configure task? Maybe we should adjust this task before it. Doxyfile(or other name) is the file which will be used by doxygen. It is one part of source code to be maintain.

Give me ten minutes and I'll find a package that builds documentation
from a file generated at build time.

Are there really that many recipes that support doxygen but don't run
it themselves at build time? I'd have expected packages that can use
doxygen to generate the documentation at build time (using DBus as an
example, if it finds doxygen at configure time it will build
documentation).

Ross