Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Multitude of warnings around lc3 and bap_lc3 when building docs #55901

Closed
aescolar opened this issue Mar 17, 2023 · 16 comments
Closed

Multitude of warnings around lc3 and bap_lc3 when building docs #55901

aescolar opened this issue Mar 17, 2023 · 16 comments
Assignees
@gmarull
Labels
area: Bluetooth Audio area: Bluetooth area: Documentation bug The issue is a bug, or the PR is fixing a bug priority: low Low impact/importance bug

Comments

@aescolar
Copy link
Member

aescolar commented Mar 17, 2023 •
edited
Loading

Describe the bug
When building Zephyr's docs there is plenty of doxygen warnings around the lc3 and bap_lc3 headers

To Reproduce
Steps to reproduce the behavior:

  1. cd ${ZEPHYR_BASE}/doc
  2. make html DT_TURBO_MODE=1

Expected behavior
No warnings

Impact
Annoyance + they shadow other warnings

Logs and console output

WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:382: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_1_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:382: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_1_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:383: found </em> tag without matching <em>
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:385: The following parameter of BT_BAP_LC3_BROADCAST_PRESET_16_1_1(_loc, _stream_context) is not documented:
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:549: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_1_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:549: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_1_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:550: found </em> tag without matching <em>
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:552: The following parameter of BT_BAP_LC3_BROADCAST_PRESET_16_1_2(_loc, _stream_context) is not documented:
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:392: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_2_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:392: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_2_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:395: found </em> tag without matching <em>
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:397: The following parameter of BT_BAP_LC3_BROADCAST_PRESET_16_2_1(_loc, _stream_context) is not documented:
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:559: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_2_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:559: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_16_2_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:562: found </em> tag without matching <em>
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:564: The following parameter of BT_BAP_LC3_BROADCAST_PRESET_16_2_2(_loc, _stream_context) is not documented:
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:404: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_24_1_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:404: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_24_1_1(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:405: found </em> tag without matching <em>
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:407: The following parameter of BT_BAP_LC3_BROADCAST_PRESET_24_1_1(_loc, _stream_context) is not documented:
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:571: argument 'em' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_24_1_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:571: argument 'stream_context' of command @param is not found in the argument list of BT_BAP_LC3_BROADCAST_PRESET_24_1_2(_loc, _stream_context)
WARNING: zephyr/include/zephyr/bluetooth/audio/bap_lc3_preset.h:572: found </em> tag without matching <em>
[....] 700+ total warnings

Environment

  • OS: Ubuntu 22.04
  • Commit SHA or Version used: 58f35ea (main as of yesterday)
  • doxygen 1.9.1
  • doc build python packages:
    breathe 4.35.0
    sphinx 5.3.0
    sphinx_rtd_theme 1.2.0
    sphinx_tabs 3.4.1
    sphinxcontrib-svg2pdfconverter 1.2.2
    Pygments 2.14.0
    sphinx-notfound-page 0.8.3
    sphinx-copybutton 0.5.1
    PyYAML 6.0
    pykwalify 1.8.0
    docutils 0.17.1
    imagesize 1.4.1
    sphinxcontrib-jsmath 1.0.1
    Jinja2 3.0.3
    sphinxcontrib-devhelp 1.0.2
    babel 2.11.0
    sphinxcontrib-applehelp 1.0.2
    requests 2.28.1
    sphinxcontrib-qthelp 1.0.3
    alabaster 0.7.12
    packaging 21.3
    snowballstemmer 2.2.0
    sphinxcontrib-serializinghtml 1.1.5
    sphinxcontrib-htmlhelp 2.0.0
    sphinxcontrib-jquery 4.1
    docutils 0.18.1
    ruamel.yaml 0.17.21
    docopt 0.6.2
    python-dateutil 2.8.1
    pytz 2022.1
    MarkupSafe 2.0.1
    charset-normalizer 2.1.1
    urllib3 1.26.5
    certifi 2022.12.7
    idna 3.4
    ruamel.yaml.clib 0.2.7
@aescolar aescolar added bug The issue is a bug, or the PR is fixing a bug area: Bluetooth Audio area: Documentation labels Mar 17, 2023
@aescolar
Copy link
Member Author

CC @Thalley @asbjornsabo

@Thalley
Copy link
Collaborator

Thalley commented Mar 17, 2023

This has been seen before: https://discord.com/channels/720317445772017664/884782246010175528/963075575226961970

This is a Sphinx/doxygen bug; can you provide the version of those that you are using to build?

@Thalley
Copy link
Collaborator

Thalley commented Mar 17, 2023

@aescolar is this only failing locally for you, or in CI?

Have you tried doing something like pip3 install --user --upgrade -r requirements-doc.txt?
I just built locally, and I don't see any of these warnings

@aescolar
Copy link
Member Author

@Thalley versions added

@Thalley
Copy link
Collaborator

Thalley commented Mar 17, 2023

Thanks. Not sure what to do about this issue: The documentation is correct and it is seemingly a Sphinx/Doxygen issue, which I cannot reproduce either with the build commands supplied by this issue.

We are using the same version of Sphinx (5.3.0), but my Doxygen version is lightly newer (1.9.6), but I don't see any reference of this issue in the Doxygen release notes. The issue with underscore was fixed back in release 1.8.14 (doxygen/doxygen#6128)

@aescolar
Copy link
Member Author

Thanks. Not sure what to do about this issue: The documentation is correct and it is seemingly a Sphinx/Doxygen issue, which I cannot reproduce either with the build commands supplied by this issue.

Feel free to close the issue then. It is not a too bad thing.

@Thalley
Copy link
Collaborator

Thalley commented Mar 17, 2023

Thanks. Not sure what to do about this issue: The documentation is correct and it is seemingly a Sphinx/Doxygen issue, which I cannot reproduce either with the build commands supplied by this issue.

Feel free to close the issue then. It is not a too bad thing.

If this is something that happens to other than you (or more importantly something that happens in CI), then we need to find a solution for it.

It doesn't seem like the Documentation Build job shows any logs from building the docs, so not sure how to verify that.

@aescolar
Copy link
Member Author

It doesn't seem like the Documentation Build job shows any logs from building the docs, so not sure how to verify that.

@stephanosio can you comment on this?

If this is something that happens to other than you

I'm using default Ubuntu 22.04 LTS packages, and default Zephyr instructions. So I'm guessing it is a relatively normal situation.

@stephanosio
Copy link
Member

Documentation build job logs, like any other workflow jobs, can be viewed through the GitHub UI.

@stephanosio
Copy link
Member

FYI @gmarull @kartben

@gmarull
Copy link
Member

gmarull commented Mar 17, 2023

Can you try Doxygen 1.9.6?

@jgl-meta jgl-meta added the priority: low Low impact/importance bug label Mar 21, 2023
@Thalley
Copy link
Collaborator

Thalley commented Mar 23, 2023

@aescolar Have you tried with a newer version of doxygen?

@aescolar
Copy link
Member Author

@aescolar Have you tried with a newer version of doxygen?

Not yet. But I presume it will not produce the warnings

@gmarull
Copy link
Member

gmarull commented Mar 23, 2023

@aescolar Have you tried with a newer version of doxygen?

Not yet. But I presume it will not produce the warnings

Some 1.9.x Doxygen versions have bugs, not sure if 1.9.1 is one of them. I know that 1.9.5 is unusable for us due to a similar issue.

@aescolar
Copy link
Member Author

@aescolar Have you tried with a newer version of doxygen?

Not yet. But I presume it will not produce the warnings

Some 1.9.x Doxygen versions have bugs, not sure if 1.9.1 is one of them. I know that 1.9.5 is unusable for us due to a similar issue.

We can close the issue if you want.

@aescolar
Copy link
Member Author

I confirm that with doxygen 1.9.6 the warnings are not present

@gmarull gmarull closed this as not planned Won't fix, can't repro, duplicate, stale Mar 23, 2023
@Thalley Thalley moved this from To do to Done in Bluetooth LE Audio Oct 4, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@gmarull gmarull

Labels
area: Bluetooth Audio area: Bluetooth area: Documentation bug The issue is a bug, or the PR is fixing a bug priority: low Low impact/importance bug
Projects
Bluetooth LE Audio
Archived in project
Milestone
No milestone
Development

No branches or pull requests
6 participants
@henrikbrixandersen @Thalley @stephanosio @gmarull @aescolar @jgl-meta