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
