Heya,
I'm trying to document my C code with doxygen, however using the "documentation after members" style doesn't seem to work for me. The doxygen documentation says:
Putting documentation after members
If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.
Here are some examples:
[...]
Most often one only wants to put a brief description after a member. This is done as follows:
int var; //!< Brief description after the member
or
int var; ///< Brief description after the member
Minmal source example:
/** #file test.c */
void foo(void) {
uint8_t bar; ///< Some random variable
}
My Doxyfile is pasted here.
Instead of getting some description of the variable in the documentation, I get this:
2.1.1 Function Documentation
2.1.1.1 void foo ( void )
< Some random variable
Anyone happens to have an idea why?
The member documentation syntax is meant for, well, members.
Members are values in a class or struct (or however your language might call it). Local variables are not members and thus not covered by doxygen.
The reason for this is that usually the members of a class are critical for its state, so you desperately want to document those, as derived classes might use protected members for example.
Functions on the other hand don't need such documentation for their local variables. After all, those are local. A function should thereby be defined by its total observable behaviour, as the local variables aren't important for the user:
struct object_type{
struct object_state_type state; ///< the object's state
};
void bad_documentation(void) {
uint8_t bar; ///< Some random variable
}
/// \brief Initializes the global state of the omnipotence object.
void good_documentation(void) {
uint8_t bar;
/** \remark The object needs to be initialized exactly once,
* otherwise we have some problems.
*/
assert(some_global_var != 0);
/** One can check `some_global_var` whether the global object
* has been initialized
*/
some_global_var = 1;
/// Finally, the object going to be initialized.
impl_obj_state_init(&the_global_object.state);
}
Doxygen allows you to document members of a file, struct, union, class, or enum. The code you have displayed is showing a local variable of a method and not a member of one of those entities.
Related
I've use quite a bit of JavaScript so far. If you were to use an object constructor in JavaScript, you have access to the this constructor.
So my question relates to trying to use a similar concept in C. I created a struct that I want to be able to self reference:
struct Storage {
void (*delete)();
}
So if I were to allocate a Storage class:
struct Storage *myStruct = malloc(sizeof(struct Storage));
Let's say I'm trying to delete myStruct. If I have some delete function that I point to (with myStruct->delete = deleteStructure), I would like to do something like this:
myStruct.delete();
which would then free() the struct through a self referencing variable inside of said delete function. I'm wondering if there would be a way to have the delete function look like:
void deleteStructure() {
free( /* "this" or some equivalent C self-reference */ );
}
My assumption from research so far is that this is not possible since this is usually only in object oriented programming languages. If this is not possible, I'm wondering what would be the semantically correct way to do this. I'm hoping to make the usage of this delete functionality rather simplistic from a user interface perspective. The only way I understand this to work would be passing a reference to the structure like:
void deleteStructure(struct Storage *someStructure) {
free(someStructure);
}
which would then require deletion to be done as follows:
deleteStructure(myStruct);
To sum up: is there a way to make a delete function that uses self references in C, and if not, what would be the most semantically correct way to delete a structure in the most user friendly way?
No. You cannot even define a function for a struct.
struct Storage {
void (*delete)();
}
simply stores a pointer to a void function. That could be any void function and when it is being called, it has no connection to Storage whatsoever.
Also note that in your code, every instance of the struct stores one pointer to a void function. You could initialize them so that they all point to the same function, in which case you would simply waste 64 bit per instance without any real benefit. You could also make them point to completely different functions with different semantics.
As per #UnholySheep's comment, the correct semantical use of a struct with connection to a C function will follow the structure:
struct Storage {
/* Some definitions here */
}
void deleteStructure(struct Storage *someStructure) {
free( /* all inner structure allocations */ );
free(someStructure);
}
Here's more about passing structs by reference.
I am creating an algorithm in C that is confidential and cannot be shared with external customers. So, I decided to go with creating a library (.a) file which compiles my algorithm and lets others use it without modifying it. It basically alters the data of a variable within a structure. Now, the structure as such is visible externally (The structure is defined in a separate header file which is included in my .c file) and is generated based on user's configuration. But the said variable is always present within the structure - only remaining data is changed based on user's configuration.
The problem is that if the structure is not exactly the one I used to create the library file, the code fails.
So is there a way to create a library file to modify the data inside a structure, if the structure itself is not available in the beginning?
Any help is greatly appreciated...
Technically all structures you use must be character by character equal everywhere. If you have any difference between the same structure in two (or more) translation units that will lead to undefined behavior.
There are ways around that though, for example by using nested structures. For example you could create one structure to contain your private data, and then another structure whose first member is an instance of the first private structure.
For example something like this:
struct private_data
{
// TODO: The private members here
};
struct public_data
{
struct private_data private;
// TODO: The public members here
};
This is in effect similar to inheritance of an object-oriented language. A pointer to the public_data structure can be cast as a pointer to the private_data structure and passed to the functions that need it.
To keep the private data, well, private you could use opaque data types and opaque pointers:
// Forward declaration of the actual private data
struct actual_private_data;
// The "public" private structure
struct private_data
{
// Pointer to the actual private data
struct actual_private_data *private;
};
It's important to note that this only works for the private data used for the library. If the public data structure contains data that needs to be accessed by the library as well, you might want to rename the private_data structure and put the common data there. Note that this common data must be in all variants of the structure, it can't be auto-generated differently than what is used in the library.
If you are interested only in one data member of a structure,Then get the address of that variable in your confidential application and modify it's value.
I am working on microntroller RZA1, with KPIT GNUARM 16 toolchain, in e2 studio. I am not an expert on the subject, so I'll try to explain the problem the best that I can. The issue is related to a structure mainwindow, defined in my code, which contains important features of the graphical interface:
typedef struct
{
page_t pages[MAXNUMPAGE];
logger_t storico;
messagges_t messaggio;
graph_t grafico;
} mainwindow_t;
In the main() function I declare a local instance of this struct, as it contains a while(1) loop, which is used to refresh the GUI application in case of user interaction (i.e pushbutton clicked). The problem that I have encountered is that there's a difference in the way program executes in case the instance of mainwindow_t is declared with or without static keyword. For instance,
main()
{
static mainwindow_t mainwindow;
....
init_pages(mainwindow.pages);
while(1)
{
page_update(mainwindow.pages);
}
}
works perfectly well, whereas with only mainwindow_t mainwindow; it seems that the changes made in the function init_pages() had no effect: entire content of the array page[MAXNUMPAGE] is uninitialized.
Therefore, my question is: should there be any functional difference between non-static local and static local declaration of an array inside a function, if that function basically never returns ?
The problem has nothing to do with whether the variable lives on the stack or not. It has to do with initialization.
Variables with static storage duration, i.e. file-scope variables or local variables with the static keyword, are implicitly initialized so that (loosely speaking) all variables with arithmetic type are initialized to 0 and all pointer variables are initialized to NULL.
In contrast, variables with automatic storage duration, i.e. variables declared inside of a function, are not initialized if there is no explicit initializer and its value is indeterminate.
While you didn't show your initialization function, it apparently doesn't set all fields in mainwindow.pages and depends on the other fields being zero-initialized. When mainwindow is declared non-static, this results in your program reading some indeterminate fields which causes undefined behavior, which explains why the problem mysteriously disappears when you attempt to trim down the code.
Adding an initializer to mainwindow addresses this issue by setting any fields explicitly listed, while applying the static object initialization rules to any remaining fields not explicitly initialized.
In one file I have a struct like...
struct t {
int private;
int public;
};
struct t s;
One way to have other object files be able to access s.public would be to put...
struct t {
int private;
int public;
};
extern struct t s;
...into a header file and the have the other files reference s.public.
I'd like to avoid this because it locks in the offset between between the base of s and the base of public in any object files that reference s.public. This means that these files would have the wrong address for public if I ever added a new private2 after private it would require a recompile.
Instead I'd like to find a way to export the location of symbol s.public as maybe s_public_direct directly rather than as s with an offset to `public. So other files would then only need the header...
extern int s_public_direct;
...and would have no knowledge of the layout (or even existence) of the structure that public happens to live in.
Is there any way to export a symbol reference for a variable that lives inside a structure in C/C++? If not, is there an elegant way to solve this problem?
Note that is not a scoping issue so marking private with C++ private: would not change the fact that the referencing object file would still get passed the base address of the enclosing struct and then would add the offset to get to public. I am really looking for some kind of C/C++ syntax that tells the compiler to export a symbol of a variable that is in inside a struct. Or maybe a way to declare a new exportable symbol like int s_public_direct as an alias for the variable inside the struct.
The easiest way to do this is to keep the type opaque and export accessor funtion(s) for the field:
extern int get_t_public(struct t *);
extern void set_t_public(struct t *, int);
This allows you to also export it read-only (by defining the get without the set), or a variety of other useful things (enforcing some constraints on the value, or caching things dependent on them and invalidating the cache when the value changes and things need to be recomputed.)
I have a C function named SetParams(...) with a variable number of arguments. This function sets up a static data structure (let us name it Data). SetParams is used with pairs of arguments, e.g. SetParams("paramA", paramA_value, "paramB", paramB_value) etc. It can also be called many times, e.g.
SetParams("paramA", paramA_value);
SetParams("paramB", paramB_value);
...
When all 'parameters' have been set, another function is called (let us name it Execute) that takes no args:
Execute();
// uses data from static 'Data' and performs error_handling and execution
I was wondering if I could structure this kind of code in a more object-oriented way. So, I would like some advice, especially for error-handling, since some pairs of args may contradict others.
The general practice for creating an object oriented design in C is for every method you have you will pass in a reference to a struct which is used to store all the classes member variables. In otherwords in C++ where you'd have listObj.clear() you have in C list_clear(&listObj).
This is kind of ugly, but it's necessary unless you want to use static member variables and limit the implementation to being used only once.
In the example below, notice how in each method a reference to a struct ParamUtilObj is passed in.
// --- paramUtil.h
// Stores all the objects member variables (public and private)
struct ParamUtilObj {
int paramCnt;
char param1[25];
char param2[25];
...
};
bool paramUtil_initialize( struct* ParamUtilObj pData );
bool paramUtil_addParam( struct* ParamUtilObj pData, const char* pKey, const char* pValue );
bool paramUtil_execute( struct* ParamUtilObj pData);
With respect to variadic methods. I'd try to avoid them if possible and just add them in one at a time. The business logic to validate the params is an entirely different topic in my opinion. I'd need more info to recommend the best approach. But... It seems to me since you're going to have to do validation such as if( MethodA ) then check for presence of some other argument... it might be easier to create several SetParam methods for each MethodType which the user could specify in the script.
I would recommend using a linked list to store your params and put all your methods as function pointers to a struct.
struct MyClass {
struct LinkedList* params;
void (*setParams)(...);
void (*execute)()
}
the linked list would be a key value pair
struct LinkedList {
struct LinkedList *next;
char * key;
char * value;
}
I dont know how you have your SetParams implemented, from the sound it just does a little bit of parsing and storing and forwards error handling downstream to the Execute call.
Since you are using variable length arguments, are you using the va_* macros? Doing so with a format string might allow you to insert the error handling into your SetParams call and allow Execute to just iterate over the values and do its thing.
Generally, if you have a function that handles setting parameters that should be where you manage errors associated with setting parameters. Errors encountered in the execution of command should be addressed in the execute function.
You cannot do it this way, because in C variadic functions don't know the number of arguments you've supplied, so you need somehow let function know it, like specifying number of params as first parameter or use printf way, when number of parameters can be found from format string.