Skip to content

Fix \param names in interp_get_base and riscv_timer_set_mtimecmp - #3165

Merged
kilograham merged 1 commit into
raspberrypi:developfrom
darkdi:doc-param-names
Sep 1, 2026
Merged

kilograham merged 1 commit into
raspberrypi:developfrom
darkdi:doc-param-names

Conversation

@darkdi

@darkdi darkdi commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Was checking doxygen output on the interp and riscv timer headers and hit two \param names that don't match the argument below them. interp_get_base documents lane, which looks copied from interp_set_base just above it, and riscv_timer_set_mtimecmp documents mtime from its neighbour. Doxygen drops unmatched names quietly so the build stays green either way. I left the mtimecmp wording alone, it still reads as if the call sets mtime and that seemed like your call.

@lurch lurch added the documentation Improvements or additions to documentation label Sep 1, 2026
@lurch

lurch commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Doxygen drops unmatched names quietly

Well that's a bit annoying 🙁

@darkdi

darkdi commented Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

I was wrong about that. It does warn, I just checked with 1.18 against the defaults docs/Doxyfile.in inherits:

t.h:2: warning: argument 'lane' of command @param is not found in the argument list of interp_get_base(void *interp, unsigned index)
t.h:2: warning: The following parameter of interp_get_base(void *interp, unsigned index) is not documented:
  parameter 'index'

Both of those, and then it exits 0. So the docs job stays green and the two lines scroll past with everything else. WARN_AS_ERROR = FAIL_ON_WARNINGS in docs/Doxyfile.in would catch the next one without changing how much output you get, it runs the whole build and only sets the exit code at the end.

@kilograham kilograham added this to the 2.3.1 milestone Sep 1, 2026
@kilograham
kilograham merged commit ab8cf1e into raspberrypi:develop Sep 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants