C++ function pointer as parameter in Doxygen

Question

I have a situation where I need to document the bsearch() signature in Doxygen. That signature looks like this:

void * __cdecl bsearch (
    const void *key,
    const void *base,
    size_t num,
    size_t width,
    int(__cdecl *compare)(const void *, const void *)
    )

The problem I am having is how to compose the @param command for the pointer *compare since Doxygen complains "argument 'compare' of command @param is not found in the argument list of bsearch" at everything I throw at it.

This is a standalone implementation, so it is not dependent on a library signature, however I am thinking if I did:

typedef int(__cdecl *pcompare)(const void *, const void *);

changing the signature to pcompare compare that callers using the standard signature would have a type problem.

I am open to ANY solution that allows me to document this without alarm from Doxygen.

Using `bsearch` is C++ code is a loss on all accounts -- it isn't typesafe, and it's slower than the equivalent C++ templated functions such as `std::binary_search` and `std::lower_bound` — Ben Voigt, May 10 '15 at 19:21
Thank you Ben. The fact of the matter is the project at hand is a modernization and customization of Libctiny, well actually minicrt, so there are some constraints. For my own usage I will chop the thing down even more than it is as my intent is to get the purists off my back over my last round of utils coming out in .NET while keeping the exe really small. — Mike Morris - MBXSW, May 10 '15 at 20:17

score 5 · Accepted Answer · edited Jun 20 '20 at 09:12

however I am thinking if I did:
typedef int(__cdecl *pcompare)(const void *, const void *);
changing the signature to pcompare compare that callers using the standard signature would have a type problem.

You should have tried it before giving up. typedef does not define a new type, it just creates a new identifier for a complex type. The resulting signatures are identical.

Be careful though, because neither of the forms shown are the correct signature. To declare A C runtime library function like bsearch you need extern "C". (and so would the function pointer typedef -- language linkage is part of the function type)

All of that said, just setting __cdecl as a predefined macro in your doxygen config would probably be sufficient to allow it to parse all of these variations, including the ones with a complex set of tokens specifying the parameter type.

I didn't actually try it because I really don't have a use for it. Documenting the runtime has been an awesome learning experience. Thank you for confirming what I thought I had read. I still have to wrap my head around the `extern "C"` which is above the` bsearch` in the file, but the `typedef` definitely does a better job of not blowing out the Doxygen sig layout. — Mike Morris - MBXSW, May 10 '15 at 20:24

score 1 · Answer 2 · answered May 10 '15 at 19:17

1

There's no problem with the typedef.
You should use it anyways --- it's clearer to read.

answered May 10 '15 at 19:17

smiling_nameless

1,047
1
9
23

C++ function pointer as parameter in Doxygen

2 Answers2