Runtime function calls produce a pessimistic callgraph

When virtual functions or function pointers are called, EDoc++ can not be certain exactly which functions will be called. In this situation, EDoc++ will assume that every function that matches the call is "possibly" being called. As a result calls to virtual functions and function pointers may be overly expanded thus possibly including more exceptions than might really occur. There is however a mechanism for the user to override the expansion of the call graph using suppressions. See Restricting call graph for possible function pointers for more information.

Obtaining function pointers dynamically through mechanisms like dlsym may cause omission of items from the callgraph.

There are a few situations where this may occur, however the most common one is when dynamically querying the address of a function symbol from a dynamically loaded library (plugin) using a function like lt_dlsym().

Additionally if the user does some non-standard things like constructing a function pointer value by specifying it manually in some environment where it is known that a particular function would always exist at a particular address. Then EDoc++ does not know the address of the function has been taken. This is probably more likely in embedded environments. I.e. If the code looks like:

/* Hey I don't even know if anything like this is valid C code */ 
FunctionPointer fp = (FunctionPointer)0xFF00CC00;

If there is a situation where something is occurring that EDoc++ is unable to determine that the address of a function is being taken, then during the suppressions stage the user will have to add that information manually before calculating exception information. See section: Adding address taken for function obtained using lt_dlsym() or equivalent for more information.

List of propagating exceptions for circularly dependant functions produces a pessimistic list of propagating exceptions.

When one or more functions participate in a circular callgraph dependency, EDoc++ may fail to accuratly determine the exceptions that may propagate from those functions. In particular it is possible that an exception raised within the circularly dependant callgraph may be filtered out by a relevant catch block, however due to technical reasons EDoc++ is sometimes unable to filter these exceptions out of the resulting data.

Unable to determine resource leaks or behavioural problems due to poor exception usage

EDoc++ primarily reports invalid usage of exceptions, it is not designed to report dangerous usage of exceptions within the context of the program. Examples of things that EDoc++ does NOT protect against include:

These problems exist when using exceptions in many languages, however problems caused by it can be minimised by using certain patterns such as RAII, ScopeGuard undo pattern (http://www.ddj.com/dept/cpp/184403758) and immutable objects.

Note also that writing code to meet certain exception safety guarantees is an important part of C++ coding. There are plans for the future of EDoc++ to help development of code to meet certain safety guarantees. Future versions of this manual will describe more about writing exception safe code and using EDoc++ to help with this. For more information on exception safety in C++ see http://www.boost.org/community/exception_safety.html

GCC Modification currently uses a lot of memory and may fail or take excessivly long times to compile large source files

Note: Intended to be fixed/improved in future releases

This is a temporary design issue. The EDoc++ GCC modification ensures that GCC does NOT garbage collect any memory associated with FUNCTION_DECL or used type tree nodes. This is because after all code generation is done just before emitting the EDoc++ data file, the GCC Modification performs a number of validations on the information it has gathered. This is primarily a debugging feature but some necessary elements currently rely on this so it can not currently be removed. As such GCC may have difficulty compiling large source files and may even fail its compilation.

This should be fixed by the first major release of EDoc++ (Not necessarily in the alpha or beta releases though)

Output generated for inclusion in doxygen is not completely compatible with existing doxygen releases.

EDoc++ uses a "canonical" format for representing the names of functions. This format is generated inside the modified GCC and often does not reflect the exact way the user declared the function. The representation is the same, but #define statements would have been substituted, the default arguments for templates are expanded and there are a few other peculiarities that cause doxygen to have troubles with the generated data.

As a result the documentation generated for doxygen sometimes creates a name that although valid, doxygen is unable to determine exactly which function is being referenced. When this occurs doxygen will OMIT the given data from the resulting HTML documentation and will emit a warning.

There are currently two workarounds for this problem.

Note: Future versions of EDoc++ will have the ability to generate documentation inline with the source which should avoid these problems.

Embedding EDoc++ data in binary files will not work on all platforms

The way EDoc++ embeds data into binary files is by adding a new section in the binary file called ".edoc". Some binary formats do not support additional sections, and so this method will fail. This is not a common situation as most platforms use the COFF format which from my understanding does support this feature.