klange / toaruos

A completely-from-scratch hobby operating system: bootloader, kernel, drivers, C library, and userspace including a composited graphical UI, dynamic linker, syntax-highlighting text editor, network stack, etc.
https://toaruos.org/
University of Illinois/NCSA Open Source License
6.03k stars 475 forks source link

Improve code documentation, and maybe generate docs #211

Open klange opened 2 years ago

klange commented 2 years ago

During my hiatus from ToaruOS in late 2020/early 2021, and as part of developing Kuroko, I started adopting javadoc/doxygen-style code comments which are now well supported in Bim. Kuroko's web documentation is actually built from the code documentation with Doxygen at the moment.

When I restarted work on Misaka in April, I adopted that code style for comments in the kernel, but the coverage remains poor.

  1. Completely document the kernel, including all APIs that are expected to be reasonably stable for modules.
  2. Convert all heading comments to Javadoc/Doxygen format to align with the kernel.
  3. (Optional) Generate kernel and library documentation from the Doxygen comments.