feat(doc): Adding Doxygen documentation to core files

[0utd4ted]

This is still a very early work in progress and the proposed documentation is still under an initial review for QA.
Get doxygen and run it in the repository to produce an HTML output in "build/doxygen/html".

[danielRep]

Thanks for the contribution @AAGandomi ! I'll try to take a look in the following days

[josecm]

Hey Aras, thanks for this (I expect, first!) PR.

I'll also be reviewing it in the coming weeks!

[0utd4ted]

Almost done with mem.c and vm.c. I will push the second and last set of commits during this coming weekend (by 01/02/2025, things came up).
They will also take care of some issues with sign-off strings in commit messages (expect a force push to update this PR) and some oversights from my part (e.g. cache.c).

[0utd4ted]

Hello @josecm and @danielRep ,
I will fix the current issues with the CI, don't worry. I think we can start to review it.

I made myself familiar to https://bao-project.readthedocs.io/en/latest/development/code_documentation.html but I have prioritize content over form. My main focus for this contribution was to capture the objective of the functions and their coupling with the rest of the software. This is meant to be a starting point.

The guidelines I have tried my best to stick to:

1. The @brief summarize in a sentence the goal of the function (its main output).
2. The "long description" had 2 objectives: describe in more details certain design choices or expand on a very generic brief description ("initialize", I'm looking at you) and highlight non-functional characteristics: logical sequences mostly, since there are no timing constraint (at this time ).
3. Never use the third person when describing the function. Use imperative form for concise descriptions.
4. Document all the functions in .c files. macros/inline functions defined in header files are left undocumented.

I have intentionally deviated from Bao's guidelines' form, which may be reverted or fixed in future iterations:

1. @pre, @post and @invariant where not used - too much effort to do correctly for a draft.
2. @note was used very liberally, to remind the reader of the presence of alternative outputs (e.g., console messages). Or any behavior that was obvious form the brief description.
3. @see has been used to list (as a best effort) all global variables, functions (static, local and external) and structs. It was done mostly as an effort to collect functions' any and all dependencies.
4. @param is assumed as input if not specified otherwise.

I can see the following improvements to be made (on top of a regular review) before merging:

• Custom doxygen special commands:
  • for placeholder functions (e.g. @notimplemented @archspecific @platformspecific.
  • for alternative intended (and unintended) outputs, as such console warnings, console errors, and exceptions (i.e. jumps to exception vector).
  • for dead ends (e.g. @noreturn)
• @post when global variables are set.
• @pre/@invariant when global variables are read.

[0utd4ted]

Hi @AAGandomi ,

My overall feeling of the review for your PR is that you have done an excellent job. I don't have major changes for now, only some typos, grammar in-corrections, and style/format inconsistencies and improvements (in my view).

I believe @josecm will help to identify if I missed something.

* No @return tags for some void functions. No hard feelings for that, but inconsistent with some other files.

* I feel that the long description should be split as in the `console_init` function. Seems more readable.

* Should we change this:

 * @return enum irq_res FORWARD_TO_VM if sent to VM
 * @return enum irq_res HANDLED_BY_HYP if handled by hypervisor
 * @return ERROR if the interrupt ID is not assigned.

For something like this as we do in the multi-line @see tag?

 * @return enum irq_res FORWARD_TO_VM if sent to VM
 *         enum irq_res HANDLED_BY_HYP if handled by hypervisor
 *         ERROR if the interrupt ID is not assigned.

Hello @danielRep ,

• According to the observed doxygen behaviour, void functions shall not have return tags. I have removed those that do.
• I agree that the console_init style may be more readable. I will spin a quick script to align all the docs to it.
• The see and return tags do not work the same way: the see tag is just a list, while each return tag can make the generated documentation easier to read. IMHO the use of multiple return tags should be up to whom write the doc (and the reviewers).

Just for reference, this is generated when using 3 different return tags:

While this is the doxygen output when only one is used (as you suggested):

The indented format used for see tags was used to keep all the elements in the same tag. I have removed the use of multiple tags, but I don't think it is a policy - multiple see tags should not affect the final product.

For context: I have introduced those see tags for collecting (manually) data in order to evaluate connascence scores. see tags may very well be removed without affecting the documentation.

@josecm @danielRep IMHO the only changes left for this PR are for linting (and CI issues). I will follow up with a new PR on CI/workflow to introduce doc linting and doxygen checks.

[danielRep]

First, sorry for the delayed reply @AAGandomi . Very busy in the last weeks, but I'm back to this activity.

Hello @danielRep ,

• According to the observed doxygen behaviour, void functions shall not have return tags. I have removed those that do.

Agree.

• I agree that the console_init style may be more readable. I will spin a quick script to align all the docs to it.

Sounds good!

Just for reference, this is generated when using 3 different return tags:

While this is the doxygen output when only one is used (as you suggested):

I see. Let's keep it as you've proposed then.

The indented format used for see tags was used to keep all the elements in the same tag. I have removed the use of multiple tags, but I don't think it is a policy - multiple see tags should not affect the final product.

For context: I have introduced those see tags for collecting (manually) data in order to evaluate connascence scores. see tags may very well be removed without affecting the documentation.

Got it.

@josecm @danielRep IMHO the only changes left for this PR are for linting (and CI issues). I will follow up with a new PR on CI/workflow to introduce doc linting and doxygen checks.

I'm on those PRs too. Let's try to push this in the following weeks as soon as @josecm get's some free time. From my part, I'm just doing a last review and approve if nothing pops up.

[0utd4ted]

Alright, no problem. I will keep pushing some more stuff here, very small stuff (typos and leftover). As per the merge, I suggest to keep the commits on specific files and then squash any following fix in 62cf5d7.