When a Doxygen group has been defined (created), all its needed to add
documentation to that group is `\addtogroup`. Since all the information
about the group is preserved, it is not necessary to mention the group
hierarchy again with `\ingroup`. This PR removes unnecessary Doxygen lines
across the `drivers`, `events`, `platform` and `rtos` directories.
It also ensures that new groups are created with `\defgroup` once and
referenced with `\addtogroup` whenever documentation needs to be added to
an existing group.
* 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`
Also includes:
* rename `mbed_sleep_manager.c` to `mbed_power_mgmt.c` to match its
header file
* create Doxygen groups for public and internal APIs
* use relative path to include header files where inconsistent
* update references to internal APIs throughout libraries
* update the copyright year for all modified files
The bulk of Callback.h was auto-generated as 6 specialisations, handling
zero to five arguments.
This can now be handled without specialisation using C++11 variadic
templates, reducing the file from 4,900 lines to 900 lines.
This should reduce compilation time, and offset potential increases from
use of `<type_traits>` or a local `mbed_cxxsupport.h` equivalent.
Several other improvents to `Callback` are possible and/or desirable
with C++11, such as the ability to store lambdas, but this commit is
purely the variadic simplification.
->move() operator was not touching unused data fields, therefore
leaving uninitialised data and failing the comparison.
Fixed by initialising all fields to zero before moving.
Fixed by zeroing the memory. A more "c++ correct" approach
may be to add an additional op for equality, and use the "=="
operator on the F type in the generate function. But this adds
the requirement that F supports equality.
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.
The attach function is used several other places to indicate
registration for interrupts. This differs significantly to its use in
the Callback class. Additionally, the attach function is unnecessary
given that simple assignment works just as well.
Adopting relaxed type-deduction in bound functions better aligns with
the same overloads for member functions, and provides an alternative
solution for the void pointer cast issue, which removes a large amount
of cruft.
The type deduction for the callback constructors was to strict and
prevented implicit casts for the context pointer stored internally.
As noted by @pan-, relaxing the contraints on the templated
parameters allows C++ to correctly infer implicit casts such as
conversions between child and parent classes when inheritance is
involved.
As an additional benefit, this may help the user experience by
defering invalid type errors to when the types are expanded,
limiting the number of error messages presented to users.
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.
Kevin Bracey
Hugues Kamba
Seppo Takalo
Martin Kojtal
kegilbert
Brendan McDonnell
Senthil Ramakrishnan
Christopher Haster
Sam Grove
Jimmy Brisson