For example, in my function
//starting code with doxygen documentation
/** The main function. I will now try to document variables within this main function*/
int main()
{
int arr[]; /** \brief an integer array*/
.....
return 0;
}
//end of code
However, when I use Doxygen with the "HIDE_IN_BODY_DOCS" variable set to "NO" in the configuration file, this does not perform specific documentation for this local variable. Rather, it just takes that bit and prints it along with the function documentation, as if it were any other comment line within the function
How can I document such local variables using Doxygen?
I do not know a way to do that (and I do doubt that there exists a way). Remember, that doxygen was made to document classes and function headers, i.e. the interface. Think of the documentation as something that other programmers study in order to use your classes and functions properly. You shouldn't use doxygen to document your implementation. However, as you are programming in C(++), it should not be a problem to document local variables in source. Just give it a proper name or document it "in source":
Cat cats[]; // holds a bunch of cats
In languages where you define all your variables must be declared at the beginning of your function(Delphi, Pascal), the system demanded by you would make sense though.
While you can put comments in the body of a function and let them appear as part of the function documentation like so
/** #file */
/** The main function. I will now try to document
* variables within this main function.
*/
int main()
{
/** an integer array. */
int arr[];
/** An endless loop */
for (;;) {}
return 0;
}
This is generally not recommended as others already pointed out. If you want (as a developer) to read the sources along with the documentation, you can better use normal C comments in the body
/** #file */
/** The main function. I will now try to document
* variables within this main function.
*/
int main()
{
/* an integer array. */
int arr[];
/* An endless loop */
for (;;) {}
return 0;
}
along with setting INLINE_SOURCES to YES.
Related
What's the best way to document the fact that a function sets some global variables? I generally prefer something that works with Doxygen as it's kind of standard and most IDEs seem to understand it, but I'm probably not going to use Doxygen to generate docs so it's not strictly necessary.
In a situation like:
extern double FIRST_VALUE;
extern double SECOND_VALUE;
/**
* Calculate the values.
* \param input The parameter used to calculate the values
* \what_goes_here FIRST_VALUE
* \what_goes_here SECOND_VALUE
*/
void calculate_values(double input)
{
FIRST_VALUE = do_magic(input);
SECOND_VALUE = do_more_magic(input);
}
(And yes, it would be nice not to use globals, but that's what I've got.)
I can put text in the detailed description, but this feels disorganized.
I saw the link http://www.cs.uregina.ca/Links/class-info/cplusplus/Standards/Disk10/aliasing_c.html about aliasing in c. The program there is shown below.
/********************************
An example of aliasing in C.
Output:
3
3
********************************/
#include < stdio.h >
int main()
{
int G_Var = 2;
/* call SomeFunction with the Global Variable as a parameter */
SomeFunction(G_Var);
return 0;
}
/* InputVar becomes an alias fo G_Var */
void SomeFunction(int &InputVar)
{
int G_Var;
int InputVar;
/* Global Variable is set to new value */
G_Var = InputVar + 1;
/* Equivalent to G_Var = G_Var + 1 */
printf("%i\n", InputVar);
printf("%i\n", G_Var);
}
Is the code correct and is working according to what is commented in the code?
Whoever wrote the link was severely incompetent and shouldn't be teaching C. They should rather enlist in a beginner's class themselves.
int G_Var = 2; is not a global variable, it is a local one with automatic storage duration. Both the one in main() and the one inside the function.
The code posted is C++, not C. C does not have references.
The term alias/aliasing refers to when several pointers (or C++ references) may be assumed to point at the same memory location.
int InputVar; in the function conflicts with the parameter name so the code doesn't make any sense. In case there were no name conflict, the variable would be uninitialized and then used, which would be senseless.
Is the code correct and is working according to what is commented in the code?
Whoever wrote this example was so confused that it's really hard to be telling what they are trying to teach, or in which language for that matter. The code does not compile for multiple fundamental reasons. Just forget about this mess.
Four things to say:
C does not have C++-kind of aliases/references. It is a C++ feature only.
So,
/* InputVar becomes an alias fo G_Var */
void SomeFunction(int &InputVar)
is wrong.
G_Var is not a global variable. You declare it two times to be local to main and SomeFunction. If you want to declare G_Var as global variable it has to be declared once at global scope, not inside of a function, and only access it by its name, not declaring its type twice.
But beside that the use of global variables is deprecated. Rather use parameter passing.
SomeFunction() isn't declared before the call to it in main(). Usually this would give you a diagnostic as the compiler don't know what SomeFunction() is.
InputVar is used as reference parameter, but also declared twice in SomeFunction. Here is a conflict.
I guess you never compiled this code before asking, which is a fault. It would have answered many questions of yours including the main one.
"Is the illustration on Aliasing in C correct?"
"Is the code correct and is working according to what is commented in the code?"
No, it isn't. The whole code is defective.
It gives the impression that the authors didn't knew how to either write correct C nor C++ code.
Detail of the problem:
Some variables are read from a fixed memory area in RAM into an array. From that array I need to read some variables and use it across the code but these variables need to be constant as they wont be changed in the program any where. Need suggestions to do it effectively! Thanks in advance for any help.
The thought was given for using const variables but then Const variables needs to be initialised during declaration itself. I need to extract bit by bit for each of these variables as I am not able to use memcpy for ensuring portability. Hence I find trouble in declaring the variables as constant.
Put those variables {myVar1, myVar2,...myVarN} into a C file myconsts.c (static to the compilation unit, this will make sure they are not visible outside). Add a header file myconsts.h with function declarations
int getmyVar1(void);
and so on for all the variables and implement the functions in myconsts.c.
They aren't const in the C sense, but they are unwriteable from outside the myconsts.c file. You can initialise them inside myconsts.c, just dont forget to call the init().
If you mean that you are trying to guarantee that these 'constants' end up in flash as opposed to your RAM memory...consult your manual.
You could use inline functions to access the data direct from the array, e.g
static inline myvar() { return array[myvaroffset]; }
Or, if you want the offsets hidden, don't use inline functions and just have a small module that just provides the functions.
If 'myvaroffset' is calculated rather than being a constant and you want to avoid the indexing overhead, copy the array element to a variable during initialisation and return that from the function. If you use real functions, the variables can be static within the function module.
in the function module
/* initialisation */
static int myvarlocal = array[myvaroffset];
...
/* function definitions */
...
int myvar() { return myvarlocal; }
When you want to use it:
i = myvar();
There is probably no need to make things complicated with const pointers etc. Simply use private encapsulation:
// data.h
int data_get (int index);
// data.c
#include "data.h"
static int the_array [N];
int data_get (int index)
{
if(index >= N)
{
// handle errors
}
return array[index];
}
I am dealing with the following issue in C. I use global variables for defining some global parameters in my code. I would like such global variables to be constant, even though they have to be initialized inside a routine that reads their values from an input data file. In a nutshell, I am looking for a good way to "cast away" constness during variable initialization in C (I guess in C++ this would not be an issue thanks to const_cast)
I came up with a pattern based on macros to do so, as illustrated below.
It seems to work fine, but I have the following questions.
Does anyone see any hidden flaw or potential danger in the procedure below?
Would anyone discourage the following approach in favor of a simpler one?
My approach:
I have a main header file containing the definition of my global variable (int N) like so
/* main_header.h */
#ifdef global_params_reader
#define __TYPE__QUAL__
#else
#define __TYPE__QUAL__ const
#endif
__TYPE__QUAL__ int N;
I have a file "get_global_params.c" implementing the initialization of N, which sees N as "int N" (as it includes "main_header.h" after defining global_params_reader)
/* get_global_params.c */
#define global_params_reader
#include get_global_params.h
void get_global_params(char* filename){
N = ... ; // calling some function that reads the value of N from
// the datafile "filename" and returns it
}
and the corresponding header file "get_global_params.h"
/* get_global_params.h */
#include "main_header.h"
void get_global_params(char* filename);
Finally, I have a main.c, which sees N as "const int N" (as it includes "main_header.h" without defining global_params_reader):
/* main.c */
#include "main_header.h"
#include "get_global_params.h"
int main(int argc, char **argv){
// setting up input data file //
...
// initialize N //
get_global_params(datafile);
// do things with N //
...
}
I hope my explanation was clear enough.
Thanks for any feedback.
Just contain the globals in a separate file.
globl.h:
struct Globals{
int N;
//...
};
extern const struct Globals *const globals;
init_globl.h:
init_globals(/*Init Params*/);
globl.c
#include globl.h
#include init_globl.h
static struct Globals _globals;
const struct Globals *const globals = &_globals;
init_globals(/*Init Params*/){
// Initialize _globals;
//...
}
Now you can initialize the globals at startup by including init_globl.h in whatever file needs access to that functionality, everyone else can directly access the globals just by including globl.h, and using the notation globals->N.
If I were you, I would simply avoid this kind of global variables. Instead, I would define a struct with all those program parameters, and define one function that returns a const pointer to the one and only instance of this struct (singleton pattern). That way, the function that returns the pointer has non-const access to the singleton, while the entire rest of the program does not. This is precisely what you need, it's clean and object oriented, so there is no reason to mess around with macros and casts.
The instance can be declared as a static variable within the function or it can be malloc'ed to a static pointer. It does not really matter, because that is an implementation detail of that function which is never leaked to the outside. Nor does the rest of the code need to be aware of when the parameters are actually read, it just calls the function and it gets the one and only object with all valid parameters.
"I would like such global variables to be constant, even though they have to be initialized inside a routine that reads their values from an input data file."
It is not possible to initialize a const in c during run-time. In c value either has or has not a const qualifier, and it is defined upon declaration. c does not support changing it. The semantics are fixed. But some expert with quoting the standard would be nicer and more ensuring.
I don't think this is possible in c++ either, but I won't bet on it, since c++ can do some magic here and there.
My situation is this:
a header aux_func.h with prototype of a function int check_format_file(FILE * file);
a source file aux_func.c with implementation of that funcion
The question is: In my main.c, where and how is better to declare FILE * f ?
As a static global variable
#include aux_func.h
static FILE * f;
int main()
{
check_format_file(f);
/* other stuffs */
return 0;
}
As an istance variable declare in main ?
#include aux_func.h
int main()
{
FILE * f;
check_format_file(f);
/* other stuffs */
return 0;
}
My doubt is about the correct visibility of FILE *f.
In both the cases, you are passing f to the one and only function check_format_file(), so there is no need to make it static and global. Nobody is going to alter the value of f (I hope so, because if somebody is going to modify it, then you have many more worries than this) and the way you are passing it to the other function, makes sure that it will be visible to the function.
From SO Question,
Variables should always have the smaller scope possible. The argument
behind that is that every time you increase the scope you have more
code that potentially modifies the variable, thus more complexity is
induced in the solution.
It is thus clear that avoiding using global variables is preferred if
the design and implementation naturally allows that. Due to this I
prefer not using global variables unless they are really needed.
I would go with the second option because it seems that you are not going to use the variable f out of this function that's why there is no reason to make it global.