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.
Related
I have some functions defined the following way:
* #brief Obtains the current time tick of the OS.
* This is a weak function and is intended to be overridden.
* #return In the weak version always 0. Otherwise should return the current
* OS time tick.
*/
__attribute__((__weak__)) osalUint_t osal_tickGetCurrent(void)
{
return 0;
}
They are defined as "weak". When I generate the doxygen output for a c file with such a definition, the function is not parsed correctly.
Is there a way to make the Doxygen be __attribute__ aware when it comes to functions (and other objects too, such as structs)?
I used as source code:
/// \file
/**
* #brief Obtains the current time tick of the OS.
* This is a weak function and is intended to be overridden.
* #return In the weak version always 0. Otherwise should return the current
* OS time tick.
*/
__attribute__((__weak__)) osalUint_t osal_tickGetCurrent(void)
{
return 0;
}
And as doxygen settings file (Doxyfile):
QUIET = YES
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
PREDEFINED = __attribute__(x)=
and the result is:
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.
I have a c-function which receives a row. The docs only displays a simple situation where integer is involved. I use DatumGetVarCharPP to get a VarChar*, because the source says DatumGetVarCharP is Obsolescent.
I debugged and found that macros VARDATA and VARSIZE which are usually used didn't return the right data. During debug I found that VarChar has a header size of 1 byte, so VARHDRSZ shouldn't be used either.
HeapTupleHeader t = PG_GETARG_HEAPTUPLEHEADER(0);
bool isnull;
Datum type = GetAttributeByName(t, "type", &isnull);
VarChar *type_text = DatumGetVarCharPP(type);
char *typestr = VARDATA(type_text);
int typestr_len = VARSIZE(type_text) - VARHDRSZ;
After research I found VARDATA_ANY and VARSIZE_ANY returns the correct pointer and size, and the header is 1 byte so real-size=size-1.
But I don't know whether it's the idiomatic way. In source I read that VARDATA_ANY don't apply to external or compressed-in-line Datum, I don't know how to check a Datum is external or compressed-in-line. Also the 1-byte offset is based on my observation during debug.
So what's the proper macros to use instead of VARDATA, VARSIZE and VARHDRSIZE? Or should I use VARATT_IS_* macros to decide the correct header size and use corresponding VARDATA_*/VARSIZE_* macros?
If you don't need the Datum aligned, use VARDATA_ANY and VARSIZE_ANY. See postgres.h:
/*
* In consumers oblivious to data alignment, call PG_DETOAST_DATUM_PACKED(),
* VARDATA_ANY(), VARSIZE_ANY() and VARSIZE_ANY_EXHDR(). Elsewhere, call
* PG_DETOAST_DATUM(), VARDATA() and VARSIZE(). Directly fetching an int16,
* int32 or wider field in the struct representing the datum layout requires
* aligned data. memcpy() is alignment-oblivious, as are most operations on
* datatypes, such as text, whose layout struct contains only char fields.
*
* Code assembling a new datum should call VARDATA() and SET_VARSIZE().
* (Datums begin life untoasted.)
*
* Other macros here should usually be used only by tuple assembly/disassembly
* code and code that specifically wants to work with still-toasted Datums.
*/
[...]
#define VARSIZE_ANY(PTR) \
(VARATT_IS_1B_E(PTR) ? VARSIZE_EXTERNAL(PTR) : \
(VARATT_IS_1B(PTR) ? VARSIZE_1B(PTR) : \
VARSIZE_4B(PTR)))
/* Size of a varlena data, excluding header */
#define VARSIZE_ANY_EXHDR(PTR) \
(VARATT_IS_1B_E(PTR) ? VARSIZE_EXTERNAL(PTR)-VARHDRSZ_EXTERNAL : \
(VARATT_IS_1B(PTR) ? VARSIZE_1B(PTR)-VARHDRSZ_SHORT : \
VARSIZE_4B(PTR)-VARHDRSZ))
/* caution: this will not work on an external or compressed-in-line Datum */
/* caution: this will return a possibly unaligned pointer */
#define VARDATA_ANY(PTR) \
(VARATT_IS_1B(PTR) ? VARDATA_1B(PTR) : VARDATA_4B(PTR))
Some background: when PostgreSQL is about to persist a table row (tuple), and the size exceeds 2000 bytes, it invokes the TOAST mechanism that first compresses some attributes and then, if that is not enough, stores them out of line. Such attributes are not immediately “deTOASTed” upon retrieval. You only do that if you need the actual values.
So if you are dealing with data that come from a table, you always have to expect TOASTed values and use the appropriate macros to deTOAST them.
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.
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
}