Skip to content

Add Doxygen comments to src/unidesk - #35

Merged
TolisSth merged 12 commits into
open-source-uom:mainfrom
YatesMold:add-doxygen
Oct 25, 2026
Merged

TolisSth merged 12 commits into
open-source-uom:mainfrom
YatesMold:add-doxygen

Conversation

@YatesMold

Copy link
Copy Markdown
Contributor

Closes #28

Doxygen was already set up on main through the CI work in #33, so this PR is the documentation part of the issue.

What changed

  • Doxyfile: PYTHON_DOCSTRING = NO (one line). With YES, Doxygen shows docstrings as plain text and ignores @brief, @param and @return. With NO, it reads them as Doxygen comments, so the generated pages get file descriptions, parameter tables and return values.
  • Docstrings in all 11 files under src/unidesk are now in Doxygen style (@file, @brief, @param, @return), one commit per file. No code changes.
  • The <name> and <filename> placeholders in text_data.py and loader.py were rewritten, because Doxygen read them as HTML tags and warned.

Checked

  • doxygen Doxyfile gives no warnings.
  • pylint src/unidesk is still clean (0 messages before and after).

Left out on purpose

  • Private methods (EXTRACT_PRIVATE = NO), functions nested inside other functions, empty __init__.py files and setup.py (not in INPUT).

Question

EXTRACT_ALL is still YES, so Doxygen does not warn about undocumented code, and a "warnings must not increase" check would have almost nothing to catch. With it set to NO, Doxygen reports 34 warnings right now: 20 for module-level constants (UI, PAGES, CONFIG_PATH and similar) and 14 for private methods and attributes of UniOSWelcome in main_window.py. Two of those (_toggle_autostart and _show_academic_config) are Doxygen reading the .connect(...) lines as variables, so docstrings cannot fix them.

I left EXTRACT_ALL on so this PR stays about the docstrings. Should I document the constants and private helpers and switch it in a follow-up, or leave that?

@TolisSth
TolisSth merged commit 3ae47e2 into open-source-uom:main Oct 25, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Doxygen

2 participants