plans on generating docs from Xen in-code comments

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

Hi all,

This email is an update in regards to the Xen documentation effort
driven by the FuSa SIG. We plan to go forward with the proposal below;
please let us know if you have any concerns.

We have been discussing how to generate documentation for Xen public
headers from in-code comments. Initially, we thought of using
kernel-doc, like the Linux kernel. kernel-doc uses a format similar to
Doxygen. I sent out a patch series to convert public headers to the
kernel-doc format in August, see [1].

Afterward, we discussed with an Intel engineer from the Zephyr project,
interested in Zephyr's safety certification. They are solving the same
problem using Doxygen. He demoed the use of Doxygen to generate
documentation and safety requirements from in-code comments and other
docs. They could produce excellent documents, suitable for safety
certifications. For example, see [2]. We should be able to reuse their
scripts and settings in Xen Project, which would save us significant
efforts. It makes sense for us to try to follow the same path with
Doxygen.

Configuring Doxygen is complex because it is much more flexible; we'll
need that flexibility. We plan to working on an appropriate Doxygen
configuration (based on Zephyr's) during the next few months. As soon as
we have it, we'll add Doxygen to Xen Project infrastructure to
automatically generate documents for the master branch (something along
the lines of http://xenbits.xenproject.org/docs/sphinx-unstable/).

In the meantime, we still intend to go ahead with the patch series [1]
to convert the public headers to kernel-doc: kernel-doc and Doxygen use
similar formats, so it is a good step in the right direction. It helps
us get closer to the final objective of Doxygen-based documents. After
we have Doxygen in place, we'll further refine the in-code comments as
necessary.

Cheers,

Stefano

[1] https://marc.info/?l=xen-devel&m=159675781406690
[2] https://docs.zephyrproject.org/latest/index.html