The Doxygen documentation says that \ingroup can be used to add an entity to multiple groups:
\ingroup (<groupname> [<groupname> <groupname>])
The problem is that I tried it and Doxygen adds the entitiy to just the last group in the group list. Something like
/** \ingroup A B
* ...
*/
adds the element to module A, but not to B. Does anyone know why, and how to solve it?
I tried it with Doxygen versions 1.7.6.1 and 1.8.1.2.
Thanks for your help.
EDIT: I realized that doxygen outputs a warning that says:
Member X found in multiple #ingroup groups! The member will be put in group B, and not in group A
It seems to me that this is contradictory with the documentation.
ANSWER: I answer myself. I was trying to add functions to multiple groups, but the documentation says "Note that compound entities (like classes, files and namespaces) can be put into multiple groups, but members (like variable, functions, typedefs and enums) can only be a member of one group".
You usually (for allowed items, lets say a file) just need to write a ingroup with multiples group. Let me show, for completeness, a template I use:
/**
* \file
* \ingroup GrpTest GrpLicense
* \brief Here your brief explanation
* \details And you put here a more detailed explanation to the
* contents of the file.
* \version 1.0
* \date 2014-09-27
* \author Dr Beco
* \par Webpage
* <<http://www.program.pg/>>
* \copyright (c) 2014 GNU GPL v3
* \note This program is free software: you can redistribute it
* and/or modify it under the terms of the
* GNU General Public License as published by
* the Free Software Foundation version 3 of the License.
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
* You should have received a copy of the GNU General Public License
* along with this program.
* If not, write to the Free Software Foundation, Inc.,
* 59 Temple Place - Suite 330, Boston, MA. 02111-1307, USA.
* Or read it online at <<http://www.gnu.org/licenses/>>.
*
*/
Now, from the Doxygen Documentation, specially the page linked here, you read:
Note that compound entities (like classes, files and namespaces)
can be put into multiple groups,
but members (like variable, functions, typedefs and enums)
can only be a member of one group
The documentation also explains why:
(this restriction is in place to avoid ambiguous linking
targets in case a member is not documented in the context
of its class, namespace or file, but only visible as part of a group).
So, for short, unfortunately you cannot add a function (or all kinds of entities, as you didn't specify, for that matter) to multiples groups.
I hope this link helps you with more questions you may have.
Use of
/** \ingroup A B
* ...
*/
will add the item to groups A and B only if they are defined elsewhere. If a group is not defined, it won't be defined just because it is used in an \ingroup command.
You should be able get the items in group B by using
/** \defgroup B
* #{
* #}
*/
/** \ingroup A B
* ...
*/
Related
I am trying to use Doxygen to document some C++ code that uses Microsoft's Source-Code Annotation Language (SAL). However, Doxygen does not parse certain annotation macros, like _Success_, correctly. In the case of the example function annotation, _Success_, Doxygen misinterprets this macro as the function header/prototype.
Take the following example that contains the function annotation marker:
/**
* #file
* Example with function annotation.
*/
#include <windows.h>
#include <sal.h>
/**
* #brief This is a function.
* #param i a random variable
* #return TRUE on every call.
*/
_Success_(return) // The SAL function annotation.
BOOL function(_In_ int i) {
return TRUE;
}
With the example above, Doxygen will interpret _Success_() as the function header/prototype and thereby, creates documentation that is absolutely wrong. Here is what the HTML Doxygen output appears like with and without the function annotation:
With the function annotation, Doxygen also says I have documented a parameter variable i that is not part of the list of arguments:
C:/.../Source.cpp:9: warning: argument 'i' of command #param is not found in the argument list of Success(return)
Am I missing a configuration setting in the main Doxygen configuration file?
Or is SAL and Doxygen simply just incompatible?
Ah ha! After some further research, I found a question on Stack Overflow that asked this same question, except it wasn't tagged correctly and did not explicitly say s/he was using "Microsoft's SAL." This is why it took me awhile to find it. (I have updated the corresponding question to correct these missteps.)
The question's answer references the Doxygen manual section entitled: Preprocessing.
A typically example where some help from the preprocessor is needed is when dealing with the language extension from Microsoft: __declspec. The same goes for GNU's __attribute__ extension. [...] When nothing is done, doxygen will be confused and see __declspec as some sort of function. [...]
Therefore, as pertaining to my example above, the settings that need to be configured in the Doxygen configuration file are as follows:
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = _Success_(x)= \
_In_=
Basically, this set of configurations means that the macros defined in the PREDEFINED section will be fully expanded and evaluated "before the preprocessor [has] started." But, these macros will expand to nothing as we provide "nothing" for the definition side of the equation (i.e. format: name=definition). Therefore, they are essentially ignored/removed while Doxygen builds the documentation documents.
Unfortunately, this does mean that one will need to continue to expand this PREDEFINED list to encapsulate, at least, all the SAL macros used in the source code. A better solution would to encapsulate all the SAL macros in this list, but future proofing is impossible as one will always be late at appending any new macros that are added later on. But, at least, there is a solution!
I just reinstalled MinGW and the Codelite IDE on my Windows PC, however I'm now unable to compile/build a project.
It is odd because every time I change a setting or make a new project, I am able to run it once, then it stops working.
I've already tried reinstalling MinGW...
This may be a bug of gcc that occurs when applying c++11 or newer standards, ie adding parameter "-std=c++11" or "-std=c++0x".
I fixed it by adding "#include "io.h"" in the file stdio.h.
you can go to your include path: "c:/mingw/include" and edit the "stdio.h".
/*
* stdio.h
*
* Definitions of types and prototypes of functions for operations on
* standard input and standard output streams.
*
* $Id: stdio.h,v 8863016e809f 2018/12/04 19:00:29 keith $
*
* Written by Colin Peters
* Copyright (C) 1997-2005, 2007-2010, 2014-2018, MinGW.org Project.
*
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice, this permission notice, and the following
* disclaimer shall be included in all copies or substantial portions of
* the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER
* DEALINGS IN THE SOFTWARE.
*
* NOTE: The file manipulation functions provided by Microsoft seem to
* work with either slash (/) or backslash () as the directory separator;
* (this is consistent with Microsoft's own documentation, on MSDN).
*
*/
#include //include at here
#ifndef _STDIO_H
#pragma GCC system_header
/* When including <wchar.h>, some of the definitions and declarations
* which are nominally provided in <stdio.h> must be duplicated. Rather
* than require duplicated maintenance effort, we provide for partial
* inclusion of <stdio.h> by <wchar.h>; only when not included in
* this partial fashion...
*/
If there is any problems or a better solution, i would appreciate your feedback very gladly.
I am studying Import Export Extension of Khronos openvx. while reading vx_import.h file I saw
VX_API_ENTRY vx_status VX_API_CALL vxReleaseImport(vx_import *import);
function.
I want to understand why they have written VX_API_ENTRY and VX_API_CALL in the function.
I am new to openvx. If anyone knows this please reply.
In the vx_types.h header you can read:
/*!
* \internal
* \def VX_API_ENTRY
* \brief This is a tag used to identify exported, public API functions as
* distinct from internal functions, helpers, and other non-public interfaces.
* It can optionally be defined in the make system according the the compiler and intent.
* \ingroup group_basic_features
*/
/*!
* \def VX_API_CALL
* \brief Defines calling convention for OpenVX API.
* \ingroup group_basic_features
*/
/*!
* \def VX_CALLBACK
* \brief Defines calling convention for user callbacks.
* \ingroup group_basic_features
*/
Then, VX_API_ENTRY is defined as empty and VX_API_CALL is defined __stdcall on Windows, and empty otherwise.
What are they for? Well, those are specifying the calling convention of the API, and at the same time, as the comment says, documenting which functions are actually public.
For example, in Windows, public functions from a DLL sometimes have declspec(__dllimport) prefixed to instruct the compiler to use the import function table, your build system can define VX_API_ENTRY for that.
The __stdcall thing is the calling convention used by this library. Usually you do not specify it and let the compiler choose the default. But in a public DLL it is a good idea not to rely to much on defaults, because the DLL compiler and the EXE compiler may use different values, and that would break the linking.
But mostly, as an end-user of the API you can just ignore them, they just work.
Except for VX_CALLBACK! You must declare your callbacks as VX_CALLBACK or you risk your code failing on some architectures (mainly Windows).
I'm trying to build the gsl library on OS X. I got the gsl-1.0 from here.
I rand ./configure in the folder followed my make.
Once I ran make, I got this:
In file included from results.c:30:
/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/../lib/clang/6.0/include/varargs.h:25:4: error: "Please use <stdarg.h> instead of <varargs.h>"
#error "Please use <stdarg.h> instead of <varargs.h>"
^
results.c:70:7: warning: implicit declaration of function 'va_start' is invalid in C99 [-Wimplicit-function-declaration]
va_start (ap);
^
results.c:73:7: warning: implicit declaration of function 'va_end' is invalid in C99 [-Wimplicit-function-declaration]
va_end (ap);
^
2 warnings and 1 error generated.
make[2]: *** [results.lo] Error 1
make[1]: *** [all-recursive] Error 1
make: *** [all-recursive-am] Error 2
I looked in the ...include/varargs.h file and found:
/*===---- varargs.h - Variable argument handling -------------------------------------===
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*
*===-----------------------------------------------------------------------===
*/
#ifndef __VARARGS_H
#define __VARARGS_H
#error "Please use <stdarg.h> instead of <varargs.h>"
#endif
Have I done something very wrong? Can I fix this?
Thanks in advance : )
Is there any way to change the version in a comment block?
For e.g.
const char VER[] = "1.2.3.4";
/**
* \version (VER)
*/
I know how to do this with preprocessing and I was wondering if there were any other way?
On a related note, how do you guys handle changing version numbers in documentation, the application, etc. without changing different version numbers all over the place? Right now I have a VER-like variable in a namespace accessible by all (essentially global without namespace pollution).
Most developers use a source control tool which usually provides a mechanism for obtaining the current revision, stringizing it, and inserting into the source. Something along the lines of
const char *VER = "$Rev$";