[asterisk-dev] Headers: Incomplete and Cyclic Referenced

[Alexander Traud]

The Google tool include-what-you-use (iwyu) works in Asterisk (for more
details see ASTERISK-25591). You can pick one single file, it goes
through the code and checks that all #include <my_required_header> are
there. I love iwyu, because it helps me to complete the inclusion
headers, especially when I submit a new module or have to update/add
stuff to existing modules. Works great.

iwyu detects a lot of issues in existing source modules:
- missing header files, previously included indirectly via other files
- orphan inclusions from removed code
- too broad inclusions, instead use a more dedicated header file
Normal stuff one would expect in a 20-year-old open-source project which
is as big as Asterisk is.

However, iwyu detects issues not only in source files (.c) but also in
public header files (include/asterisk/*.h). Those face the very same
issues above. Surprisingly many headers files in Asterisk are incomplete
themselves. Plus, with iwyu you find cyclic references, because you can
test each header file individually. These are nasty because you have to
include other headers in a specific order in your source file to build
Asterisk at all.

However however, as an external contributor, although many of those
issues are small and fast to fix, I cannot do much about those issues in
headers because decisions must be made. Sometimes, even about the
architecture.

Could someone at Digium go through at least the public header files in
include/asterisk and complete those? That would help module maintainers
to keep their inclusions correct. By this, you are going to find cyclic
references, some easy to fix via forward declarations. However, some are
not that easy to fix because structures do not use pointers as they
should.