Add path from clang to doxygen document include header

[yamaguchi]

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

[v.g.vassilev]

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]

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

[teemperor]

[teemperor]

@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]

@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" .

[teemperor]

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]

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

[v.g.vassilev]

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]

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]

docs/doxygen.cfg.in

158

Yes, I think so.

[yamaguchi]

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

[v.g.vassilev]

LGTM!

[v.g.vassilev]

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

docs/doxygen.cfg.in

 
 INLINE_INHERITED_MEMB  = NO
 
 # If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path
 # before files name in the file list and in the header files. If set to NO the
 # shortest path that makes the file name unique will be used
 # The default value is: YES.
 
-FULL_PATH_NAMES        = NO
+FULL_PATH_NAMES        = YES
 
 # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path.
 # Stripping is only done if one of the specified strings matches the left-hand
 # part of the path. The tag can be used to show relative paths in the file list.
 # If left blank the directory from which doxygen is run is used as the path to
 # strip.
 #
 # Note that you can specify absolute paths here, but also relative paths, which
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        = ../..
+STRIP_FROM_PATH        = @abs_srcdir@/..
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
 # header file to include in order to use a class. If left blank only the name of
 # the header file containing the class definition is used. Otherwise one should
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    =
+STRIP_FROM_INC_PATH    = @abs_srcdir@/..
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
 # support long names like on DOS, Mac, or CD-ROM.
 # The default value is: NO.
 
 SHORT_NAMES            = NO
 
 # If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
 # first line (until the first dot) of a Javadoc-style comment as the brief

 # The default value is: NO.
 
 SHOW_GROUPED_MEMB_INC  = NO
 
 # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
 # files with double quotes in the documentation rather than with sharp brackets.
 # The default value is: NO.
 
-FORCE_LOCAL_INCLUDES   = NO
+FORCE_LOCAL_INCLUDES   = YES
 
 # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the
 # documentation for inline members.
 # The default value is: YES.
 
 INLINE_INFO            = YES
 
 # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the