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

[Burton, Ross]

On 16 May 2014 11:18, Zongchun YU <b40527 at freescale.com> wrote:
>>>Also I think this should be opt-in not forcibly enabled as not everyone would want API documentation to be generated.
> [Zongchun] Yes. it is opt-in. the source code of packages should be written follow the rules of doxygen. If not. doxygen will not generate docs.

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.


>>>Pretty sure you'll want to run doxygen after do_compile in case the documentation is generated from files built at compile time.  But don't most packages that use doxygen invoke it themselves?  You're also not actually installing the documentation anywhere.
> [Zongchun] doxygen just use source code(follow the rules of doxygen) of packages to generate docs. not use files built at compile time. Some packages may just need to fetch and patch the source code and then generate docs. the configure file of doxygen have options to specify the generated docs types and location. Whether install the docs may depend the packages.

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}.

Ross