Add path from clang to doxygen document include header
ClosedPublic

Authored by yamaguchi on Apr 15 2017, 6:21 PM.

Details

Summary

This is an update patch for [1].

(Eg,
Changed "#include <Sema.h>" to #include "include/clang/Sema/Sema.h"

[1] https://bugs.llvm.org/show_bug.cgi?id=19260

Diff Detail

yamaguchi created this revision.Apr 15 2017, 6:21 PM

Did you have a look at the attached patch at the bug? We should not show the full path but only say, 'include/clang/Sema/Sema.h'. This would help new users to find easier how to include.

yamaguchi updated this revision to Diff 95410.Apr 16 2017, 9:54 AM
yamaguchi retitled this revision from Add absolute path to doxygen document include header to Add path from clang to doxygen document include header.
yamaguchi edited the summary of this revision. (Show Details)

Changed absolute path to path from clang source directory.
E.g #include "include/clang/Sema/Sema.h"

@yamaguchi Did you test the latest revision of this patch and get the desired output paths? I just tested it and it seems on my system doxygen can't handle the @abs_srcdir@/../.

At least on my system it gets correctly generated as:

STRIP_FROM_PATH        = /home/teemperor/llvm/trunk/tools/clang/docs/../

However, because doxygen seems to be only doing string-matching, it doesn't understand that /home/teemperor/llvm/trunk/tools/clang/ equals /home/teemperor/llvm/trunk/tools/clang/docs/../ (at least on my system). If I manually remove docs/../ I get the correct result.

In theory we could just replace the @abs_srcdir@/../with another CMake variable that is already correctly replaced by the real path, but I fear we loose autoconf support that way unless we have a separate doxygen-cmake.conf.in or something ugly like that.

yamaguchi added a comment.EditedApr 16 2017, 4:17 PM

@teemperor
Doxygen couldn't handle @abs_srcsdir@/../ , so I changed it to @abs_arcdir@/.. in Diff 95410, then it worked OK.
Document will now show the path of #include "include/clang/Sema/Sema.h" .

Woops, my bad, seems like I tested just before you fixed it.

Because I read in the documentation that we could also pass include paths here, we could also try something like this:

STRIP_FROM_INC_PATH    = @abs_srcdir@/..
STRIP_FROM_INC_PATH    += @abs_srcdir@/../include/clang
STRIP_FROM_INC_PATH    += @abs_srcdir@/../include/clang-c

That way we have the actual compiler include paths in there and we probably get the fully working #includes one has to do for a certain class. Could you test that? Something like #include "Sema/Sema.h" for the Sema class would be IMHO the best solution.

Not sure what STRIP_FROM_PATH is doing, but I think we can leave it at it's current value?

Otherwise I think this review is ready to go.

yamaguchi updated this revision to Diff 95434.Apr 17 2017, 5:18 AM

It worked, and this code generates #include "Sema/Sema.h".

v.g.vassilev added inline comments.Apr 17 2017, 6:04 AM
docs/doxygen.cfg.in
158

We should be stripping @abs_srcdir@/../include because in reality the way the user will include those files is via `#include "clang/Sema/Sema.h" for instance.

yamaguchi added inline comments.Apr 17 2017, 6:13 AM
docs/doxygen.cfg.in
158

Do you mean we should be stripping

@abs_srcdir@/../include

rather than

@abs_srcdir@/..
@abs_srcdir@/../include/clang
@abs_srcdir@/../include/clang-c

?

teemperor added inline comments.Apr 17 2017, 6:33 AM
docs/doxygen.cfg.in
158

Yes, I think so.

yamaguchi updated this revision to Diff 95436.Apr 17 2017, 6:49 AM

This will generate #include "clang/Sema/Sema.h" .

This revision is now accepted and ready to land.Apr 20 2017, 2:04 AM

Landed in r300825. Maybe we should do something like that for LLVM documentation, too.

v.g.vassilev closed this revision.Apr 27 2017, 10:06 AM