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.

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

renderer: use retval type for the retval fields #749

Merged
merged 1 commit into from
Nov 7, 2021

Conversation

gmarull
Copy link
Contributor

@gmarull gmarull commented Oct 1, 2021

This change makes @retval fields to render as a separate list, independent of the @return/s entries.

Depends on sphinx-doc/sphinx#9691

Example:

/**
 * @brief Foo.
 *
 * @param[in] bar Bar
 *
 * @retval 0 If succeeded
 * @retval 1 If something went wrong
 */
int foo(int bar);

image

@gmarull gmarull changed the title rendered: use retval type for the retval fields renderer: use retval type for the retval fields Oct 1, 2021
@jakobandersen
Copy link
Collaborator

jakobandersen commented Oct 1, 2021

Good idea, though:

  • This will only go well in general if the C++ domain of Sphinx gets the same feature, so I made C++, add retval info field sphinx-doc/sphinx#9694.
  • To avoid bumping the minimum version requirement of Sphinx to 4.3 I suggest making this conditional on the Sphinx version. I.e.,
          if sphinx.version_info[0:2] < (4, 3):
              fieldListName = {
                  "param": "param",
                  "exception": "throws",
                  "templateparam": "tparam",
                  "retval": "returns",
              }
          else:
              fieldListName = {
                  "param": "param",
                  "exception": "throws",
                  "templateparam": "tparam",
                  "retval": "retval",
              }

Similarly, the hax to collect retvals (the whole conditional code at https://github.com/michaeljones/breathe/blob/327374db4cc440bec39dd4c6f96471035aa56317/breathe/renderer/sphinxrenderer.py#L899) should be disabled if the Sphinx version is at least 4.3. While I don't think it does harm, it's nice to have the version check so it's clear it should be deleted at some point.

This change makes @RetVal fields to render as a separate list,
independent of the @return/s entries.

Signed-off-by: Gerard Marull-Paretas <[email protected]>
@gmarull
Copy link
Contributor Author

gmarull commented Oct 4, 2021

Thanks for the tips @jakobandersen, I've updated the patch.

@gmarull
Copy link
Contributor Author

gmarull commented Nov 4, 2021

@michaeljones ping

@jakobandersen jakobandersen merged commit 199eb2b into breathe-doc:master Nov 7, 2021
@jakobandersen
Copy link
Collaborator

Looks good, thanks!

@gmarull gmarull deleted the use-retval branch January 24, 2022 10:32
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.

2 participants