1

For very simple functions I would like to only have a \return section, but still show it as brief. (How) Can this be done?

For example:

/**
\return The distance.
*/
template <typename R = int64_t>
R distance(const pcg32 &other);

this generates no \brief in the docs, whereas e.g. this does:

/**
Multi-step advance function (jump-ahead, jump-back).
\param distance the distance.
*/
template <typename T>
void advance(T distance);

See this screenshot:

enter image description here

Tom de Geus
  • 5,625
  • 2
  • 33
  • 77
  • Which version of doxygen? When I understand it correctly you want to show in the brief description the text that normally appears in in the return section. Only way I can think of is to to get the text as `\brief` and as `return` and set `REPEAT_BRIEF=NO`, otherwise make a complete example showing (in text what you would like to accomplish). – albert Apr 21 '21 at 15:45
  • @albert Thanks. I'm on 1.9.1. I want to do exactly what you state. However, I'd prefer a non-global settings. In pseudo-code, what would be great is if I could set `\return Lorem ipsum \brief == \return` – Tom de Geus Apr 21 '21 at 15:51
  • I'm not aware of a possibility to accomplish this (and actually I don't see a use case for this either). – albert Apr 21 '21 at 16:04
  • @albert I guess that the only advantage is that one really has a single statement like here, currently either the is no "brief" entry in the class overview (when `\return` is used), or no 'details' entry (when nothing is used), and thus no link to the source. So if one wants both one have to use `\brief` *and* `\return`, which imo somethings leads to repititions. – Tom de Geus Apr 21 '21 at 17:57
  • This indeed lead to repetitions, but I see no other way and like I wrote before: "I don't see a use case for this either" – albert Apr 22 '21 at 08:12

1 Answers1

1

I believe that the brief section is meant to hold single paragraphs, while the \return command actually generates a header along with a paragraph.

In order to avoid changing any global REPEAT_BRIEF settings, I'd suggest a simple macro to be used for this case, e.g.,

  • Add the following to the doxygen ALIASES configuration:
    "briefreturn=**Returns** "
  • Use in your description comment like so:
/** \briefreturn the value that it returns */
int foo();

This would give you a one-line brief that is similar to the multi-line output from \return.

Modifying the macro, you can achieve other behaviors as desired, e.g., forcing generation of a details section, even when no other details supplied but the return:

"briefreturn{1}=**Returns** \1 \details. "

This can still be followed by details in the normal manner. Note that will have a leading ".", though. (Perhaps some other non-whitespace character can be used instead that is less offensive as a leading sentence character)

mattgately
  • 932
  • 8
  • 22
  • Thanks! What I think is still different is that in this case there is no detailed function description being generated, just the brief (I guess because there are no arguments, nor return) – Tom de Geus Sep 01 '21 at 15:35
  • Correct. To force generation of details, even when no section would normally be generated, then you may need to adjust macro and add a dummy `\details` in there somewhere. I thought this question was more about getting the single-line return into the brief section. I think forcing the generation of a detailed section is an easier problem. – mattgately Oct 21 '21 at 15:39
  • It was both in fact. Your solution is great, and I don't think that for such small functions one really needs a detail. But it would be still nice to know how one should do it. – Tom de Geus Oct 22 '21 at 06:46
  • Note that the question was edited after my last comment to give an example which produces details and brief. I tested to make sure it worked. I guess another option would be to use the macro to put in the brief return statement and an actual `return` statement at the same time. Lots of improvements possible... – mattgately Oct 22 '21 at 11:56