Re: [RFC PATCH 00/11] docs: Use doxygen to support html documentation

[Stefano Stabellini <stefano.stabellini@xxxxxxxxxx>]

Hi Luca,

Thank you for sending this series, it is pretty good! Please go ahead
and send it to xen-devel, we can follow the regular review cycle there.

Just a couple of suggestions before you do that.

I would avoid adding #ifdef DOXYGEN to workaround the lack of support
for anonymous structs and unions. If there is really no way to make
Doxygen understand anonymous structs and unions, then it is better to
replace them all in the Xen code base, basically taking the "#ifdef
DOXYGEN" code path and removing the other.

I would also remove the various "`incontents" comments you see through
the code because they are used to generated the old docs. As we are
adding support for Doxygen they are not needed anymore.


Finally, from a release perspective, there is still time until Jan 15 to
send out new series for Xen 4.15 and until Jan 29 to get them accepted.
So technically this series could still make 4.15 if you send it out
before Jan 15. However, in practice it is unlikely to meet the Jan 29
target because it touches many common headers so it is likely to spur
discussions.

Cheers,

Stefano


On Thu, 3 Dec 2020, Luca Fancellu wrote:
> The following series of patches based on master 
> (3ae469af8e680df31eecd0a2ac6a83b58ad7ce53)
> is an example of how we can use doxygen to improve the actual 
> (work-in-progress) html
> documentation generated by sphinx.
> 
> To test it follow these steps from the root folder:
> 1) ./configure
> 2) build xen for your favorite arch
> 3) make -C docs sphinx-html
> 
> The last step will generate the html documentation under docs/sphinx/html, 
> the file
> index.html is the home page of the documentation.
> 
> Luca Fancellu (11):
>   docs: add doxygen support for html documentation
>   docs/doxygen: Fix doxygen warnings
>   docs/doxygen: Add doxygen tags to xen.h
>   docs/doxygen: Add doxygen tags to arch-arm.h
>   docs/doxygen: Add doxygen tags to grant_table.h
>   docs/doxygen: Add doxygen tags to sched.h
>   docs/doxygen: Add doxygen tags to elfnote.h
>   docs/doxygen: Add doxygen tags to event_channel.h
>   docs/doxygen: Add doxygen tags to features.h
>   docs/doxygen: Add doxygen tags to xs_wire.h
>   docs: document hypercalls on sphinx generated html
> 
>  .gitignore                                    |    3 +
>  docs/Makefile                                 |   23 +-
>  docs/conf.py                                  |   48 +-
>  docs/hypercall-interfaces/ARM.rst             |   43 +
>  .../hypercall-interfaces/ARM/dom0_console.rst |   10 +
>  docs/hypercall-interfaces/ARM/elf_notes.rst   |   10 +
>  .../ARM/event_channels.rst                    |    8 +
>  .../hypercall-interfaces/ARM/grant_tables.rst |    8 +
>  .../ARM/guest_scheduler_operations.rst        |    7 +
>  .../ARM/hypercall_calling_convention.rst      |    7 +
>  .../ARM/list_of_hypercalls.rst                |    7 +
>  .../ARM/start_of_day_memory_layout.rst        |    9 +
>  .../start_of_day_shared_data_structure.rst    |   12 +
>  .../ARM/supported_hypercalls.rst              |    7 +
>  .../ARM/xen_elfnote_features.rst              |    9 +
>  .../ARM/xenstore_wire_protocol.rst            |    9 +
>  docs/hypercall-interfaces/index.rst           |    9 +
>  docs/hypercall-interfaces/x86_32.rst          |    4 +
>  docs/hypercall-interfaces/x86_64.rst          |    4 +
>  docs/index.rst                                |    8 +
>  docs/xen-doxygen/customdoxygen.css            |   36 +
>  docs/xen-doxygen/doxy-include.sh              |   35 +
>  docs/xen-doxygen/footer.html                  |   21 +
>  docs/xen-doxygen/header.html                  |   56 +
>  docs/xen-doxygen/mainpage.md                  |    5 +
>  docs/xen-doxygen/xen_project_logo_165x67.png  |  Bin 0 -> 18223 bytes
>  docs/xen.doxyfile.in                          | 2319 +++++++++++++++++
>  xen/include/public/arch-arm.h                 |   23 +-
>  xen/include/public/domctl.h                   |   21 +
>  xen/include/public/elfnote.h                  |   68 +-
>  xen/include/public/event_channel.h            |   34 +-
>  xen/include/public/features.h                 |   48 +-
>  xen/include/public/grant_table.h              |   92 +-
>  xen/include/public/io/xs_wire.h               |   17 +
>  xen/include/public/kexec.h                    |   10 +
>  xen/include/public/memory.h                   |   15 +
>  xen/include/public/platform.h                 |   60 +-
>  xen/include/public/sched.h                    |   18 +-
>  xen/include/public/sysctl.h                   |    5 +
>  xen/include/public/vcpu.h                     |   10 +
>  xen/include/public/xen.h                      |  199 +-
>  xen/include/xen/config.h                      |   22 +
>  xen/include/xen/errno.h                       |    6 +
>  xen/include/xen/sched.h                       |    5 +
>  44 files changed, 3231 insertions(+), 139 deletions(-)
>  create mode 100644 docs/hypercall-interfaces/ARM.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/dom0_console.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/elf_notes.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/event_channels.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/grant_tables.rst
>  create mode 100644 
> docs/hypercall-interfaces/ARM/guest_scheduler_operations.rst
>  create mode 100644 
> docs/hypercall-interfaces/ARM/hypercall_calling_convention.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/list_of_hypercalls.rst
>  create mode 100644 
> docs/hypercall-interfaces/ARM/start_of_day_memory_layout.rst
>  create mode 100644 
> docs/hypercall-interfaces/ARM/start_of_day_shared_data_structure.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/supported_hypercalls.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/xen_elfnote_features.rst
>  create mode 100644 docs/hypercall-interfaces/ARM/xenstore_wire_protocol.rst
>  create mode 100644 docs/hypercall-interfaces/index.rst
>  create mode 100644 docs/hypercall-interfaces/x86_32.rst
>  create mode 100644 docs/hypercall-interfaces/x86_64.rst
>  create mode 100644 docs/xen-doxygen/customdoxygen.css
>  create mode 100755 docs/xen-doxygen/doxy-include.sh
>  create mode 100644 docs/xen-doxygen/footer.html
>  create mode 100644 docs/xen-doxygen/header.html
>  create mode 100644 docs/xen-doxygen/mainpage.md
>  create mode 100644 docs/xen-doxygen/xen_project_logo_165x67.png
>  create mode 100644 docs/xen.doxyfile.in
> 
> -- 
> 2.17.1
> 
>