Request: showing parameter list and return type in function descriptions

[gennaroprota]

Hi,

even in its brief description, I often refer to the parameters of a function. For instance, I might have:

//!     Calculates the product of \c a and the square of \c x.
int square( int a, int x ) ;

For such a function, DocsForge would display something like:

F | square | Calculates the product of a and the square of x.

without the function parameters (or the return type), so the documentation would look like something extracted at random without a context :-) Could you please show the parameter list and the return type? This is especially important when functions are overloaded. (I have a vague memory that we quickly touched this topic, but I can't remember the details.)

[erez-o]

I see.

Brief is always stricted by the text of the first row until the end period. I need to check but I think reutrn value is also added.

The problem is that if you add parameters, return value, even some would like warnings, it stops being a short brief, and opinionated what sould and should not be in a brief.

What i can do is add a flag in the configuration that lets you choose what you want to do when doxygen @brief command is not used. Either brief will be calculated using the first row, or brief will show the entire description with show more/less buttons.

Does that solve the issue?

[erez-o]

Attaching a screenshot of how it would look with such a flag (brief = description unless @brief is specified)

[gennaroprota]

Oh, sorry that you did all that work. Actually, what I meant was to show the parameter list and the return type in the first column, together with the function name.

[erez-o]

I understand.

It was a actually a design decision not to display the parameters because it often becomes too long. Usually the the template parameters will also need to be added.

For example, for the functionbegin https://breeze.docsforge.com/master/api/breeze/begin/#overload3 you would need to add the full synopsis:

template <typename T, std::ptrdiff_t n>
    constexpr T * begin(T(&a)[n]) noexcept

So the following:

F | begin | ...

will turn to:

F | `template <typename T, std::ptrdiff_t n> constexpr T * begin(T(&a)[n]) noexcept | ...

I think it's too long for a table cell, and the focus on the overview API page should be more about brief documentation one wrote. Note that I chose a relatively short synopsis, there are far longer ones.

If you want, I can add a feature request to show the full synopsis on hover, but it's not a simple task and will take time to implement.

[gennaroprota]

Hi,

sorry for the very late reply. I'm not sure what the best solution is. Tooltips on hover might do it, but they are not good e.g. for mobile devices, which have no mouse pointer. Since it also takes time to implement, I'd suggest waiting a bit, to see if we can come up with a better idea (unless you have already implemented it in the meantime---sorry again for taking so long to respond).

BTW, are you interested in making DocsForge work on mobile devices? I noticed a little glitch that occurs when I browse the documentation from my phone, but wasn't sure whether reporting it or not.

Thanks.