Doxygen: how to document a non-C function using only its documentation block but not the code?

Question

I want Doxygen to document the code written in C-like language (PARI/GP) but having slightly different syntax. I believe Doxygen can document the entities those do not exist. It seems to be the simplest way to do the job while the programming language is not Doxygen-supported. I want something like this:

/*!
 \fn foo(param,{option})
 \brief some brief description here
 \param[in](param) mandatory parameter description
 \param[in](option) optional parameter description
*/
/*! \cond DOXYGEN_SHOULD_SKIP_THIS */
foo(param, {option}) =
{
    ...
};
addhelp(foo, "help message for `foo` function");
/*! \endcond */

Unfortunately, Doxygen generates the warning "documented symbol 'foo' was not declared or defined" and does not list the foo in an output HTML. Is there any way to force the Doxygen to produce the proper HTML using only the documentation blocks but not the code?

Answer 1

There are various options

1. You could write an input filter that translates your code into something that looks enough like C for doxygen to parse it (see also FILTER_PATTERNS and EXTENSION_MAPPING).

2. You could create a dummy C file with the function prototypes and document those instead. You could put the documentation in the C file or in your programming language if you use the approach you mentioned in the question.

3. If your language supports a C preprocessor, you could use doxygen's C preprocessor to hide parts of the file from doxygen, i.e.

   #if DOXYGEN_ONLY
   /**
    \brief some brief description here
    \param[in](param) mandatory parameter description
    \param[in](option) optional parameter description
   */
   void foo(param,option);
   #endif
   foo(param, {option}) { ... };
   

   and then define the following in the config file:

   PREDEFINED = DOXYGEN_ONLY