Annotate facade header with IWYU export annotation

[hzeller]

Without that annotation, tools such as clang-tidy or the clangd language server (as well as many other tools) will complain about headers not directly providing a symbol if users include geometry.hpp; With this annotation, they know.

Documentation IWYU
https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md#iwyu-pragma-begin_exportsend_exports

Documentation llvm include cleaner/clang-tidy/clangd https://clangd.llvm.org/design/include-cleaner#iwyu-pragmas

[barendgehrels]

hi Henner, thanks for your PR.

Given the fact that it is a clang pragma, widely used by many users nowadays, we can think about something compiler specific indeed.

Do you annotate all, or more, Boost Libraries?

[hzeller]

Not really a super clang-specific pragma.
These first showed up in the IWYU tool set (more than a decade ago), then later got also adopted by the clang include cleaner and clang-tidy.

Anyay, yes I have open pull request for a few so far. Next to geometry, also for asio, beast, and polygon.

[tinko92]

I have no strong opinion on this, so I approve. Since in the commit itself there is not much to review, some general observations:

• Grepping through my entire boost with all libraries checked out at current develop finds no existing IWYU pragma comments (just mentions in .clang-format), so BG would be the first to do this.

grep "IWYU" boost/libs -n -r
boost/libs/parser/.clang-format:46:CommentPragmas:  '^ IWYU pragma:'
boost/libs/locale/.clang-format:60:CommentPragmas:  '^ IWYU pragma:'
boost/libs/mysql/.clang-format:88:CommentPragmas: '(^ IWYU pragma:)|(^\\copydoc )|(^ ?\\n)'
boost/libs/nowide/.clang-format:53:CommentPragmas:  '^ IWYU pragma:'
boost/libs/histogram/.clang-format:39:CommentPragmas:  '^ IWYU pragma:'
boost/libs/redis/.clang-format:84:CommentPragmas: '(^ IWYU pragma:)|(^\\copydoc )|(^ ?\\n)'
boost/libs/yap/.clang-format:46:CommentPragmas:  '^ IWYU pragma:'

• Including e.g. boost/geometry/geometries/geometries.hpp (which is suggested in the BG documentation page for the models) would arguably less objectionable from an IWYU-perspective than including boost/geometry.hpp AFAIU but it also declares nothing and would presumably need the same pragmas. Should this be on more headers then?

[hzeller]

adding a pragma to boost/geometry.hpp won't help much as it in itself includes another facade header, and IWYU will only follow one level deeper. So in my project, i'll include boost/geometry/geometry.hpp and am thus only one level removed (and this is why I only added the annotation there)

[tinko92]

Thank you for clarifying.

If I test with the tool, e.g.

#if defined(LEVEL0)
#include <boost/geometry.hpp>
#elif defined(LEVEL1)
#include <boost/geometry/geometry.hpp>
#elif defined(LEVEL2)
#include <boost/geometry/geometries/geometries.hpp>
#else
#include <boost/geometry/geometries/box.hpp>
#include <boost/geometry/geometries/point_xy.hpp>
#endif

using point = boost::geometry::model::d2::point_xy<double>;
using box = boost::geometry::model::box<point>;

int main() {
    box a;
    return 0;
}

That gets me (where ./geometry is your branch)

include-what-you-use main.cpp -I./geometry/include -I../boost/ -DLEVEL0 # case 1: complains
include-what-you-use main.cpp -I./geometry/include -I../boost/ -DLEVEL1 # case 2: your include, still complains, on your branch
include-what-you-use main.cpp -I./geometry/include -I../boost/ -DLEVEL2 # case 3: deeper include, still complains
include-what-you-use main.cpp -I./geometry/include -I../boost/ # case 4: no complaint (actually including what is used)

So this PR, will suppress a warning from a tool that seems arguably valid (including all of boost geometry is usually including more than what is used, there are specific headers for using specific interfaces) but only if boost geometry is included in way different from what is documented and what most people are probably doing (<boost/geometry/geometry.hpp> instead of <boost/geometry.hpp>) and then not in all cases, only if at least one class or method is used that is declared in a header directly included by boost/geometry.hpp. Is this correct and could any of this be improved?

Would we also want this pragma on e.g. boost/geometry/geometries/geometries.hpp and similar headers like these (in particular the facade headers that are recommended for use by the current boost documentation)? If I add the pragma to the geometries.hpp header, it silences the warning for case 3, still not for case 2 though.

[hzeller]

It looks like there is no perfect solution as IWYU only follows the exports pragmas one level deep (I am not using the include-what-you-use but the clangd language server and clang-tidy that also have these implemented). If you use the clangd language server and include the header, it will complain in the editor about headers not defining the symbol directly included.

Maybe the private pragma can help ? https://github.com/include-what-you-use/include-what-you-use/blob/master/docs/IWYUPragmas.md#iwyu-pragma-private ... i have not explored that

[barendgehrels]

I think it's good to add a comment (one or two sentences) giving the background,
like you did in the PR (maybe more concise). Otherwise this will raise questions after a year or two (by possibly new developers).