Skip to content

Update for Doxygen 1.9.5 #119

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 4, 2023
Merged

Update for Doxygen 1.9.5 #119

merged 3 commits into from
Jan 4, 2023

Conversation

multiplemonomials
Copy link
Collaborator

@multiplemonomials multiplemonomials commented Jan 3, 2023

Summary of changes

This MR updates the code and CI job to use a newer version of Doxygen, 1.9.5. It was pointed out that even after #118 there were still some errors showing up in the docs when using this version, so those should be resolved now.

Basically, Doxygen 1.9.5 made four changes that we need to handle:

  • Added some new options to the doxyfile and deprecated others. I upgraded the current doxyfile using doxygen -u.
  • Doxygen now warns when an @param is added to an entity that does not have parameters. In particular, this means that mbed::Callback<...> declarations cannot take parameters. I emulated the style of parameters using <br> and \c tags.
  • Due to False warning "@param documentation sections but no arguments" on using declarations/typedefs doxygen/doxygen#9552, warnings are also erroneously generated for function pointer typedefs, even though these can take parameters. This is fixed in Doxygen 1.9.6, but we don't have ready access to this version through github actions, so we'll have to live with it for now.
  • Doxygen now warns when a @return tag is applied to something that is not a function. This helped find several errors in the docs where documentation was attached to the wrong entities.

I've updated the code to account for all of these things and fix the warnings. Here's what the new pseudo-parameter formatting looks like:
image
It's honestly not half bad, IMO.

Impact of changes

Migration actions required

Documentation

(this is a docs update)


Pull request type

[X] Patch update (Bug fix / Target update / Docs update / Test update / Refactor)
[] Feature update (New feature / Functionality change / New API)
[] Major update (Breaking change E.g. Return code change / API behaviour change)

Test results

[] No Tests required for this change (E.g docs only update)
[X] Covered by existing mbed-os tests (Greentea or Unittest)
[] Tests / results supplied as part of this PR

Reviewers


@multiplemonomials multiplemonomials merged commit 280d40c into master Jan 4, 2023
@multiplemonomials multiplemonomials deleted the dev/doxygen-1.9.5 branch January 4, 2023 05:26
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.

3 participants