sphinx-doc / sphinx-doc/sphinx

[C++] Top-level `const` and `volatile` should not be present for function parameters

Open
#11,441 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domains:cpp
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
  1. Create a default Sphinx project.
  2. Add .. cpp:function:: int square(int const x, int volatile y); to index.rst.
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.