Doxygen: Force undeclared functions to be documented

问题

Our C++ program has a built-in script interface and is able to run scripts in it. The scripts have access to convenience functions provided by the C++ program.

Now we would like Doxygen to create the documentation of the functions the script has access to. Such a function declaration looks like this:

void ScriptEngine::load_script(const QString &path) {       
//...

    /*! \fn sleep_ms(const unsigned int timeout_ms)
        \brief sleeps for timeout_ms milliseconds.
        \param timeout_ms 
    */
    (*lua)["sleep_ms"] = [](const unsigned int timeout_ms) {
        //sleep(timeout_ms)
    };

    //more convenience functions..
//...
}

Obviously Doxygen won't include a

sleep_ms(const unsigned int timeout_ms)

into the documentation. Is there a way to to tell Doxygen to do so?

回答1:

Do this:

Add the following line to your Doxyfile:
```
PREDEFINED = _DOXYGEN_
```
Make sure the ENABLE_PREPROCESSING tag in the Doxyfile is set to YES.

Put your declarations and documentation for the undeclared functions inside an #ifdef _DOXYGEN_ section.

#ifdef _DOXYGEN_
    /*! \fn sleep_ms(const unsigned int timeout_ms) 
        \brief sleeps for timeout_ms milliseconds.
        \param timeout_ms
    */
    void sleep_ms(const unsigned int timeout_ms);
#endif

Don't put the above code inside a method or function such as ScriptEngine::load_script(), as you previously tried. And don't put it inside a namespace or class, unless in fact the function being declared is a member of that namespace or class.

With this method, your declarations will not create linker errors during a normal build, but will be seen by Doxygen.

See Also

http://www.doxygen.nl/manual/config.html#cfg_predefined

来源：https://stackoverflow.com/questions/42510536/doxygen-force-undeclared-functions-to-be-documented

标签

doxygen