* Change Doxygen groups structure, splitting first by Public/Internal
This commit also does the following:
* groups the documentation of related API
* moves `events/internal/equeue.h` to `events/equeue.h`
* merges `events/source/README.md` to `events/README.md`
Separate drivers, events, and rtos internal APIs from public APIs.
* Move source files to source subdirs
* Move internal headers to internal subdirs
* Add Doxygen comments for documenting internal and public APIs
* Remove source code from header files in order to remove include pre-processor directives
that included header files not directly used by said header files
* Explicitly include header files instead of implicit inclusions via third-party header files.
Release Notes
This will break user code that was using an internal API as the internal header files have been moved.
This will only break if the user was including the header file using a namespace (i.e #include "foo/bar.h" instead of #include "bar.h"
Unwind previous commit and restore original behaviour for binding,
pending further investigation.
Some functions like `EventQueue::call` require precisely matching
argument types to get the correct overload, as before.
Others like `EventQueue::event` permit compatible types for binding, and
those handle the 0-5 bound arguments non-variadically in order to
correctly locate the free arguments in deduction.
Previous commit just replaced instances of "class B0, class B1, class
C0, class C1" with "class... BoundArgs, class... ContextArgs".
This loses the requirement that the numbers must match.
Now, the original code was also inconsistent as to whether it used
separate types for the target function and the call input parameters.
Some forms just used B0, B1 as parameters rather than separate C0, C1.
I believe the separate parameters would have been primarily to avoid
template deduction confusion - eg if int was supplied to a B0 parameter
but the function took char as B0, there would be an ambiguity. But the
fix didn't seem to be fully applied.
Rewritten all templates parameterising on function pointer type and
input arguments so that they use `type_identity_t<BoundArgTs>...` as
input parameters to match the target function.
This has the subtle effect that any conversion happens at invocation,
before storing to the context, rather than when the context calls the
target.
Variadic templates can reduce Event.h from 4,100 lines to 300, and
EventQueue.h from 3,400 to 1,000, so 6,000 lines saved total.
End result isn't totally variadic, as we still need specialisations
for storing 0-5 values in contexts, but that specialisation is now
in exactly one place.
Only change other from switching to variadic templates is using
delegating constructors instead of the `new (this)` trick. That trick is
still used in the assignment operator.
Minor documentation correction. It's possible that the separate
simplified variadic Doxygen version not be needed now, but I've left it.
- Removed Makefile from branch
- Moved a0..a4/c0..c4 parameter documentation from top level overloaded functions to each function to appease Doxygen.
- Removed @see Event::Event from overloaded functions as the link did not work and the argument parameter documentation was moved down to each function
- TODO: Cleanup EventQueue.h
stop using scope for \addtogroup. It was placing class methods into the
group documentation instead of the class documentation. The new style is
to explicitly tag the class as @ingroup. This new method will allow the
class to be linked in the group page, and the class page will contain
the detailed documentation of the class methods.
While limitations in type inference prevent the event helper from
infering the type of generic function objects, there is nothing
technical preventing inference from the Callback class, where the
function type is encoded in the template parameters.
With adoption of the Callback class as the standard function
representation, it makes sense to support events created from
callback objects.
In the IAR ide, implicitly generated structures based on function
templates end up with missing type information. This has no effect
on using the IAR compiler standalone, but when used through the ide
the missing type information causes the ide to error.
As a workaround, moved the function attributes generated for the
Callback and Event classes into the class scope. This avoids the
syntax that confuses IAR.
Added mbed-events from https://github.com/ARMMbed/mbed-events. Changes
from upstream:
- the whole code is licensed under the Apache license. Sources and
headers were updates with this information.
- removed the porting layers for Windows and FreeRTOS and the references
to these porting layers in equeue_platform.h.
- moved the TESTS directory in mbed-events to the TESTS directory of
mbed-os.
Hugues Kamba
Kevin Bracey
Martin Kojtal
kegilbert
Brendan McDonnell
Jimmy Brisson
Christopher Haster
Sam Grove
Bogdan Marinescu