Xen Summit 2023 Design Session: Doxygen

[Henry Wang <Henry.Wang@xxxxxxx>]

Hi all,

Below is the note that I've taken for the doxygen design session. Please 
correct me
if I made mistakes. Thanks.

Luca: this is to discuss our current documentation and improvements.
      We started at Arm 2 years ago to introduce sphinx and doxygen.
      There are some problems as doxygen sometimes needs some in-code comments.
      Wondering if having doxygen in Xen is a good idea, we can start from
      maintaining 2 docs in the project, one is the current and the other is 
      the experimental one and then evolve from there.
Luca: we have a series Arm internally, we need to rebase it again and again.
S: We have a scripts by Ian Jackson available to do things related to the doc 
   and the website. The script is unmaintained now and we might need to get
   rid of it. doxygen is better in terms of maintenance than perl, but the 
   problem is doxygen is not really "improvement" of the doc itself.
J: It is more about, for example, list all the hypercalls description in the 
   same doc instead of maintaining the large series.
S: If we want to have 2 docs, we need to keep consistent between docs, the 2
   docs should both have complete information about every hypercalls.
L: We can start from smaller steps, maybe we can just start to construct the 
   new doc instead of directly introduce the hypercall description.
B: if we agree the doxygen is the format we go with, the change is more or
   less mechanical, but the problem is to determine the format we will use
   and the correct things to do, like how we build the doc
S: agreed
B: doing the mechanical change should not change the existing contents at all.
   Otherwise it is hard to review. we need also to take notes about the 
   possible improvements during the review, and gitlab would be a good place
   to have such noted down.
L: our build system is able to build sphinx and html based doxygen doc. can we 
   push something to the community about introducing such doc?
B: Also take the opportunity to introduce the gitlab pipeline for building the
   doc
Alejandro: I know there is a way to do that
Anthony & S: someone knows the xenbits webpage and doc would be good to spend
   some time to help
B: we need to keep the old doc for a while because we need also to provide the 
   doc for older xen releases
L: suggestions about introducing the doxygen
S & B: I would start with a 1 to 1 doc instead of too many redirections and 
   things complicated
L & J: Since an agreement is more or less reached to start to introducing the 
   doxygen + sphinx, maybe we can continue the discussion in the next community
   call to involve other community members unavailable today
Anthony & Bertrand: we start from use doxygen to replace what it is current now
   and then even start to work on constructing the function API doc using 
   doxygen in the future. This is useful also for MISRA.
Luca: For now I cannot commit anything to it, but I will ask for internal
   opinions and others can also contribute to this.

Kind regards,
Henry