search

tomtom-international / asciidoxy

AsciiDoxy generates API documentation from Doxygen XML output to AsciiDoc.
Apache License 2.0
31 stars 10 forks source link

C functions with function pointer as argument are not parsed correctly #121

Open spickartz opened 5 months ago

spickartz commented 5 months ago

When running asciidoxy on a Doxygen output from:

/**
 * @brief My func.
 *
 * My longer function description.
 *
 * @param [in] arg      An important argument.
 * @param [in] func_ptr A callback function.
 * @param [in] priv     Argument to the func_ptr callback.
 */
void my_func(void *arg,
             void (*func_ptr)(int elem, void *priv),
             void *priv);

There seem to be issues with the parsing of the func_ptr argument (cf. full output below):

DEBUG: No name found in `*`
WARNING: Could not fully parse `void(*)(int elem, void *priv) `. Links to known types may be missing.
DEBUG: Unexpected trailing token(s) `(`,`int`,` `,`elem`,`,`,` `,`void`,` `,`*`,`priv`,`)`,` ` in `void`,`(`,`*`,`)`,`(`,`int`,` `,`elem`,`,`,` `,`void`,` `,`*`,`priv`,`)`,` `

The resulting HTML shows the function as (cf. output of MWE):

#include </home/runner/work/asciidoxy-mwe/asciidoxy-mwe/my_include.h>

void my_func(void * arg,
             void(int elem, void *priv) (*) func_ptr,
             void * priv)

which does not match with the sources and results in further errors (e.g., the description of parameters is partly set in bold due to the misplaced asterisk). I have created a MWE and uploaded it to GitHub for further analysis: https://github.com/spickartz/asciidoxy-mwe

The issue is reproducible with GitHub actions:

Output of asciidoxy ... --log DEBUG ...:

Run asciidoxy --spec-file packages.toml --log DEBUG index.adoc
    ___              _ _ ____             0.8.7
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/
Collecting packages     : 0pkg [00:00, ?pkg/s]DEBUG: Using selector: EpollSelector
Collecting packages     : 100%|██████████| 1/1 [00:00<00:00, 1134.52pkg/s]
Loading API reference   : 0pkg [00:00, ?pkg/s]WARNING: Could not fully parse `*`. Links to known types may be missing.
DEBUG: No name found in `*`
WARNING: Could not fully parse `void(*)(int elem, void *priv) `. Links to known types may be missing.
DEBUG: Unexpected trailing token(s) `(`,`int`,` `,`elem`,`,`,` `,`void`,` `,`*`,`priv`,`)`,` ` in `void`,`(`,`*`,`)`,`(`,`int`,` `,`elem`,`,`,` `,`void`,` `,`*`,`priv`,`)`,` `
Loading API reference   : 100%|██████████| 1/1 [00:00<00:00, 589.92pkg/s]
Resolving references    : 0ref [00:00, ?ref/s]DEBUG: Resolved refs: 0
DEBUG: Still unresolved: 0: 
Resolving references    : 0ref [00:00, ?ref/s]
Checking references     : 0ref [00:00, ?ref/s]
Checking references     : 0ref [00:00, ?ref/s]
Preparing work directory: 0pkg [00:00, ?pkg/s]
Preparing work directory: 100%|██████████| 2/2 [00:00<00:00, 428[6](https://github.com/spickartz/asciidoxy-mwe/actions/runs/8297825325/job/22709766902#step:9:7).46pkg/s]
Processing asciidoc     :   0%|          | 0/1 [00:00<?, ?file/s]INFO: Preprocessing index.adoc
INFO: Processing index.adoc
Processing asciidoc     : 100%|██████████| 2/2 [00:00<00:00, 134.18file/s]
INFO: Running AsciiDoctor...
Copying images          : 0pkg [00:00, ?pkg/s]
Copying images          : 100%|██████████| 2/2 [00:00<00:00, 140[7](https://github.com/spickartz/asciidoxy-mwe/actions/runs/8297825325/job/22709766902#step:9:8)4.[8](https://github.com/spickartz/asciidoxy-mwe/actions/runs/8297825325/job/22709766902#step:9:9)5pkg/s]