i can link to the enum documentation with the # symbol
in the generated html it links to the the enum
when put the mouse over the link there is a tooltip with the text of the documentation
how can i get the text of the documentation ?
when i write somewhere #MY_ENUM i get a link but how can i get the text and not only a tooltip
for example in enum.h i write this
/**
* #file enums.h
*/
typedef enum{
MY_ENUM = 0x1, ///< Some text
}SOME_ENUM;
and in an other_header.h i write this
/**
* #file other_header.h
*/
/**
* Funktion Description
*
* Values for SOME_ENUM can be<br>
* #MY_ENUM
*/
int some_function( SOME_ENUM parameter );
in the html documentation for some_function a link to MY_ENUM is generated
but i whould like to have the Text 'Some text' after the link
or is it possible to insert the hole SOME_ENUM table there ?
When I interpret the question you would like to see in the output something like:
did you try:
#MY_ENUM \copybrief MY_ENUM
as this will give the result of the image.
See also my answer https://stackoverflow.com/a/68889048/1657886 to a similar question.
Related
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
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.
I would like to use the Doxygen grouping mechanism for data structures. I'm already using it for functions and it works well so far. What I've experienced so far fits to the documentation regarding member groups of a single type (e.g. function only) or mixed type (e.g. typedefs and functions).
Now I tried to extend these member groups with data structures, and this fails exceptionally. Data structures are always a top section on its own. My tries so far:
Put a data structures definition inside an existing mixed type member group. -> Data structure is still documented in a separate top level section.
/**
* \file doxytest.h
*/
/**
* \name Iteration API
* \brief Some documentation. Group will be on top level.
*/
/// #{
/**
* \brief For no reason this is not part of the member group.
*/
typedef struct {
/**
* \brief Some mask
*/
uint32_t mask;
} filter_t;
/**
* \brief Some variable
*/
extern const uint32_t MODE_FILTER_MASK;
/**
* \brief Curiously this IS part of the member group.
*/
typedef bool (*for_each_cb)(const void *obj, void *opaque);
/**
* \brief Some function
*/
uint32_t filter_id_filter_set(size_t ids_num, ...);
/// #}
Side by Side of final Doxygen output and desired Doxygen output (Photoshopped)
Creating a group solely consisting of data structures. -> Data structures are documented in a separate top level section and the documentation block for this group vanishes completely.
/**
* \file doxytest2.h
*/
/**
* \name Structures
* \brief This documentation block will not show up
* in the final file documentation. It is completely lost.
*/
/// #{
/**
* \brief Won't show up in group/section "Structures"
*/
typedef struct {
/**
* \brief Some mask
*/
uint32_t mask;
} filterA_t;
/**
* \brief Won't show up as well
*/
typedef struct {
/**
* \brief Some mask
*/
uint32_t mask;
} filterB_t;
/// #}
/// Some struct that should not show up in group "Structures"
typedef struct {
int bar;
} someStruct;
Side by Side of final Doxygen output and desired Doxygen output (Photoshopped)
Use a module and add the data structures mit \ingroup. -> Data structure pops up in the module, but the file documentation still looks the same as above
Using \nosubgrouping command on file level documentation. -> No changes at all to file documentation page.
/**
* \file doxytest.h
* \nosubgrouping
*/
I would like that the documentation for file doxytest.h/doxytest2.h displays data structures in the group they were defined in.
The programming language is C, but I'm very limited in terms of changing the code to fit documentation needs. Doxygen version is 1.8.16. The configuration file is almost default. (I left out stuff like project name and input settings)
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
SORT_MEMBER_DOCS = NO
DISABLE_INDEX = NO
Any help appreciated.
It took me several months to find, but the answer was deceptively simple.
You just need to enable INLINE_SIMPLE_STRUCTS:
# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions
# with only public data fields or simple typedef fields will be shown inline in
# the documentation of the scope in which they are defined (i.e. file,
# namespace, or group documentation), provided this scope is documented. If set
# to NO, structs, classes, and unions are shown on a separate page (for HTML and
# Man pages) or section (for LaTeX and RTF).
# The default value is: NO.
INLINE_SIMPLE_STRUCTS = YES
The fact that the data structures are "simple" is only a consideration of every member being publicly accessible, not the number of entries.
Now I have a bunch of C source files with already inserted comments, which are in format /*****......*****/ for functions and /*....*/ for phrases and variables. My task is to document these files with doxygen. The problem is obvious: the comment formats are not supported by doxygen. So I have to find a way to modify the comment format of the files and also add other further comments.
I've tried with gvim with doxygen toolkit. I was only able to insert something simple like
/**
* #brief
*/
only to functions. So I'm wondering if there's a way for me to modify the already existing comments. Thank you in advance.
For Vim:
\/\*\*\*\*\*\_.\{-}\*\*\*\*\*\/
Finds
/*****
abcdef
*****/
void main()
{
int a = 0;
/**** abcdef ****/
}
/***** abcdef *****/
void function()
{
}
/*****
abcdef
abcdef
abcdef
*****/
void function2()
{
}
Which can easily be convert to a sub expression replacement VIM command:
:1,$ s/\(\/\*\*\*\*\*\)\(\_.\{-}\)\(\*\*\*\*\*\/\)/\/\*\*\2\*\//g
:)
Perhaps python/grep-awk would be a better choice here!
EDIT: Comment - Above solution is strictly based on the /***** pattern (i.e. number of '*' in /*****)
We have a function header format that we have to follow. It basically looks like this
/**
* Name: blah
*
* Parameters:
* int foo
* bool bar
*
* .....
We are attempting to generate some documents with doxygen, but one issue is that when we change he code to:
/**
* Name: blah
*
* Parameters:
* \param int foo
* \param bool bar
*
* .....
When Doxygen generates the html comments, it adds the Parameters title. We are required to have line 4, so this creates documents with 2 lines that say Parameters, the first is from line 4 and the second Doxygen auto inserts.
What I'm hoping I can do is either have Doxygen ignore line 4 or add have it not insert it's own "Parameters:" title. Anyone know if this is possible?
The simple solution is to remove the "Parameters:" text altogether; it is entirely redundant since the Doxygen mark-up makes it perfectly clear that they are parameters!
For that matter the "Name:" label is entirely redundant too, and forces you to place the name in both the comment and the code. Why would you need that? It's name is right there in the code. It is an unnecessary comment maintenance headache, and Doxygen will use teh name in the code not the name in the comment in the generated documentation.
If you must attempt to mix your existing format with a Doxygen compatible format it would be easier to use C++/C99 line comments rather than block comments; most C compilers support them:
// Name: blah
//
// Parameters:
/// \param foo Description of foo
/// \param bar Description of bar
Note \param <type> <name> is not correct Doxygen syntax; it is \param <name> <description>. Doxygen gets the type from the code; again specifying the type in the comment is entirely redundant, and another maintenance headache.
I would strongly suggest that you employ a more Doxygen and maintenance friendly function boiler-plate altogether. I use the following basic form (for what its worth):
//! #brief Brief description
//!
//! Full description if necessary.
//! #param p1 p1 description
//! #param p2 p2 description
//! #return Return value description
int foobar( int p1, int p2 ) ;
Obviously whether you use /// or //! and \ or # is a matter of preference.
I've got some C code from a 3rd party vendor (for an embedded platform) that uses global variables (for speed & space optimizations). I'm documenting the code, converting to Doxygen format.
How do I put a note in the function documentation that the function requires on global variables and functions?
Doxygen has special commands for annotating parameters and return values as describe here: Doxygen Special Commands. I did not see any commands for global variables.
Example C code:
extern unsigned char data_buffer[]; //!< Global variable.
/*! Returns the next available data byte.
* \return Next data byte.
*/
unsigned char Get_Byte(void)
{
static unsigned int index = 0;
return data_buffer[index++]; //!< Uses global variable.
}
In the above code, I would like to add Doxygen comments that the function depends on the global variable data_buffer.
You can just add a note to that effect and use the \link directive to direct the reader to the description of the global variable.
Doxygen could do with an #global command to complement #param. Until that day arrives you could approximate it with aliases.
In your Doxygen configuration file add the following aliases:
ALIASES += global_START="<dl class=\"params\"><dt>Globals</dt><dd><table class=\"params\">"
ALIASES += global_{2}="<tr><td class=\"paramname\">\1</td><td>: \2</td></tr>"
ALIASES += global_END="</table></dd></dl>"
Example of usage:
int fxnMAIN_Main(void)
{
/**
* #brief Bla Bla Bla.
*
* #global_START
* #global_{bExampleOne, Description Here}
* #global_{bExampleTwo, Second Description Here}
* #global_END
*
* #retval int : Bla Bla Bla.
*/
// Code Here
}