sphinx-doc / sphinx-doc/sphinx
[C++] Top-level `const` and `volatile` should not be present for function parameters
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
void f(int), void f(int const), and void f(int volatile) are all the declarations for the same overload A C++ best-practice is to not const-qualify proper function declarations, and only function definitions. This is because one can declare f as void f(int const), and then define it as void f(int). You can verify this using this Compiler Explorer example.
Note that this doesn't apply to references. void f(int&) and void f(int const&) are different overloads, as demonstrated by this second Compiler Explorer example.
Top-level const-qualifier is redundant at best, but it's potentially misleading, since a reader may interpret this to mean that x won't change, which isn't guaranteed by a proper declaration, since the definition can change this up.
How to Reproduce
- Create a default Sphinx project.
- Add
.. cpp:function:: int square(int const x, int volatile y);toindex.rst. - Run
make html.
Environment Information
Platform: linux; (Linux-6.3.2-arch1-1-x86_64-with-glibc2.37)
Python version: 3.11.3 (main, Apr 5 2023, 15:52:25) [GCC 12.2.1 20230201])
Python implementation: CPython
Sphinx version: 6.2.1
Docutils version: 0.18.1
Jinja2 version: 3.1.2
Pygments version: 2.15.1
Sphinx extensions
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue in a default Sphinx project by adding the cpp:function directive to index.rst and running make html. Trace how the C++ signature is parsed and rendered, using the examples in the report to distinguish top-level qualifiers from reference qualifiers; done means the generated documentation omits redundant top-level const and volatile qualifiers without changing reference overloads.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100