1

I have a problem with doxygen. Not all my \todo are collected in the global todo list, but most of them. I have made a simple C-example with a single source and header file, as well as a configuration file, where i have placed todos everywhere i want doxygen to collect them into the global todo list.

My global todo list is missing the shown todos in the below code snippet, meaning the one inside the body of my public function (test_todo12 in myFunc), as well as the ones in the cfg file (test_todo16 and test_todo17), both implemented as shown below.

test.h:

/**
 * Definition of test structure.
 */
typedef struct def_struct_
{
    int32_t first;     /**< First element.*/
    int32_t second;    /**< Second element. */
    int32_t third;     /**< third element. */
} def_struct_t;

/**************************************************************************************************/
/**
 * \brief   My func description.
 *
 * \param[ in ] test_param Input parameter to myFunc.
 *
 * \return      bool
 * \retval      false   false on non success.
 * \retval      true    true on success.
 *
**************************************************************************************************/
bool myFunc( uint32_t test_param );

test.c:

#include <stdint.h>
#include <stdbool.h>

#include "test.h"

#include "test.cfg"

bool myFunc( uint32_t test_param )
{
    uint32_t testVar = test_param ;

    //! This function does nothing. \todo test_todo12
    testVar++;

    return true;
}

test.cfg:

/** test cfg
 * \todo test_todo16
 */
 static def_struct_t test_cfg[2] = 
 {
     .first = 123 //! \todo test_todo17
 }

I am using doxygen version 1.8.14

The differences in my doxygen configuration file compared to the default settings are the following (after trying alot of different combinations):

OPTIMIZE_OUTPUT_FOR_C  = YES
TOC_INCLUDE_HEADINGS   = 1
TYPEDEF_HIDES_STRUCT   = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
INTERNAL_DOCS          = YES
HIDE_SCOPE_NAMES       = YES
WARN_NO_PARAMDOC       = YES
RECURSIVE              = YES
EXCLUDE_PATTERNS       = */README.md 
EXAMPLE_RECURSIVE      = YES
SOURCE_BROWSER         = YES
GENERATE_TREEVIEW      = YES
USE_MATHJAX            = YES
GENERATE_LATEX         = NO
CLASS_DIAGRAMS         = NO
HAVE_DOT               = YES
UML_LOOK               = YES
DOT_PATH               = "C:\Program Files (x86)\Graphviz2.38\lib\release\lib"
DOTFILE_DIRS           = "C:\Program Files (x86)\Graphviz2.38\lib\release\lib" \ "C:\Program Files (x86)\Graphviz2.38\bin"
PLANTUML_JAR_PATH      = C:\tools\plantUML

and added *.cfg \ to FILE_PATTERNS

Link to the full compilable code and doxygen configuration (minimal example for showing this problem): Link to code

When i navigate to the public function "myFunc" i see the todo, it is just missing in the global todo list.

The cfg file does not seem to be included in the doxygen documentation at all, event though it is included in the C file, and theby should be seen as a part of this file? Or is it really necessary to do something extra/special for including these cfg files? If so, does someone know what I am missing?

I hope someone can help me solve my problem, maybe the todo in the public function body is even a bug?

Regards Jesper

Jesper J
  • 21
  • 4
  • Welcome, it is no go good to have the code in a external resource as this might not be persistent and people don't like to click on it, so include a [Minimal, Complete, and Verifiable example](https://stackoverflow.com/help/mcve) in the question. Regarding the doxygen configuration file (which version are you using?), present the differences with the standard Doxyfile (with the current version of doxygen, 1.8.16, just `doxygen -x Doxyfile` will do). – albert Oct 14 '19 at 08:28
  • At the person who says the question should be closed as it is off-topic, OP has a problem with generating the right results for the documentation with doxygen and I think the question is OK here. – albert Oct 14 '19 at 08:30
  • Thanks albert. I'll try to make a minimal example if that is prefeered. I though put up the full code, as I myself would prefeer this in this case, as it would be much easier to compile than inserting things yourself. – Jesper J Oct 14 '19 at 10:53
  • Biggest problem for me is the external link and the full code will probably contain a lot of non relevant code / documentation. For debugging and talking about it is easier (in my opinion) to have a small, complete in the sense of documentation, example . – albert Oct 14 '19 at 11:00
  • The external code is also a minimal example, special made for showing this problem, I have though included inline code snippets now :) – Jesper J Oct 14 '19 at 11:30

1 Answers1

1

Looks like there are a number of issues here.

  • the extension cfg is not known to doxygen and only adding it to FILE_PATTERNS is not sufficient, also the language in which it is written has to be made known to doxygen, so EXTENSION_MAPPING = cfg=C.
  • the variable in the test.cfg is missing a semi-colon (;) at the end. last line should read };
  • the comment inside the initialization is not considered by doxygen as documenting something (also in the current version 1.8.16 this is not considered). Problem would be where does it belong, for a \todo is would be clear that it can land on the ToDo page, but should it also land with the variable itself? and how about other comments (initializations are now variables). As a side note when using STRIP_CODE_COMMENTS=NO the comment is not shown in the initialization either.
Marc Alff
  • 8,227
  • 33
  • 59
albert
  • 8,285
  • 3
  • 19
  • 32
  • Thanks, much appreciated! You are right with the missing semi-colon. I have also added the EXTENSION_MAPPING now, and i can see in the terminal, that it now treats .cfg as c language. However, I do still not see either of the todos in the todo list. I get your point about where it belongs, does this also include the top comment in my cfg file?. So is there anything I can do to get these in the todo list? If doxygen is "skipping them", I guess something with ALIASES would not work either? Is it the same story with the todo inside "myFunc", as it does not belong to anything special? – Jesper J Oct 14 '19 at 12:32
  • For the top `\todo` in the cfg you can do probably 2 things: add `/// \file` plus an empty after it in the cfg file or you can set `EXTRACT_ALL=YES` though I think the `\file` is better. Something with ALIASES will indeed not give a solution. The `\todo` of the function is "given" to the function. I see the todo's 12 and 17. – albert Oct 14 '19 at 12:59
  • Thanks. I have now updated to the newest version of Doxygen, and it solves the problem with todo12, which I do also get in the global list now. I have tried both the \file and EXTRACT_ALL method, none of them brings todo 17 into the list. 16 is howevver fine now. I will be using EXTRACT_ALL if possible, as adding \file will most likely be forgotten by some developers who might not be so focused on doxygen yet. So for now, i am only missing todo17, but didn't you say that it was not possible to include this, as it was in an initialization which did not belong to something? – Jesper J Oct 14 '19 at 13:59
  • Problem with EXTRACT_ALL is that a number of warnings will be suppressed that otherwise would be shown. – albert Oct 14 '19 at 14:35
  • I see the problem with EXTRACT_ALL and the suppressings, also for our future use of Doxygen in regards to warnings. Can you elaborate a bit on todo17, which you said you got into your list? I still do not get it into mine regardless of what i do. – Jesper J Oct 15 '19 at 05:22
  • Sorry typo, I got not 12 and 17 but 12 and 16. – albert Oct 15 '19 at 11:50
  • Argh, I kind of feared that! So you see no method of including these, as there are inside the initialization of the variable and thereby are skipped totally be Doxygen? – Jesper J Oct 15 '19 at 11:56
  • Indeed, maybe worth to file an issue at https://github.com/doxygen/doxygen/issues/new – albert Oct 15 '19 at 12:01