It's possible that the "comment AST" may be replaced or split out in the
midterm, any anyway this makes the headers easier to read.
Developers don't currently need to include "clang-c/Documentation.h" explicitly
and there's no macro to test for availability yet.
The raw comment and brief comment accessors have been kept in Index.h though
brief support may also move here as a separate proposal.
This is not a deprecation, just a gentle separation of concerns as we look to
simplify the built-in representation of comment nodes and support external
comment processors.
llvm-svn: 207392
Let me tell you a tale...
Within some twisted maze of debug info I've ended up implementing an
insane man's Include What You Use device. When the debugger emits debug
info it really shouldn't, I find out why & then realize the code could
be improved too.
In this instance CIndexDiagnostics.cpp had a lot more debug info with
Clang than GCC. Upon inspection a major culprit was all the debug info
describing clang::Sema. This was emitted because clang::Sema is
befriended by DiagnosticEngine which was rightly required, but GCC
doesn't emit debug info for friends so it never emitted anything for
Clang. Clang does emit debug info for friends (will be fixed/changed to
reduce debug info size).
But why didn't Clang just emit a declaration of Sema if this entire TU
didn't require a definition?
1) Diagnostic.h did the right thing, only using a declaration of Sema
and not including Sema.h at all.
2) Some other dependency of CIndexDiagnostics.cpp didn't do the right
thing. ASTUnit.h, only needing a declaration, still included Sema.h
(hence this commit which removes that include and adds the necessary
includes to the cpp files that were relying on this)
3) -flimit-debug-info didn't save us because of
EnterExpressionEvaluationContext, defined inline in Sema.h which fires
the "requiresCompleteType" check/flag (since it uses nested types from
Sema and calls Sema member functions) and thus, if debug info is ever
emitted for the type, the whole type is emitted and not just a
declaration.
Improving -flimit-debug-info to account for this would be... hard.
Modifying the code so that's not 'required to be complete' might be
possible, but probably only by moving EnterExpressionEvaluationContext
either into Sema, or out of Sema.h. That might be a bit too much of a
contortion to be bothered with.
Also, this is only one of the cases where emitting debug info for
friends caused us to emit a lot more debug info (this change reduces
Clang's DWO size by 0.93%, dropping friends entirely reduces debug info
by 3.2%) - I haven't hunted down the other cases, but I assume they
might be similar (Sema or something like it). IWYU or a similar tool
might help us reduce build times a bit, but analyzing debug info to find
these differences isn't worthwhile. I'll take the 3.2% win, provide this
small improvement to the code itself, and move on.
llvm-svn: 190715
Remove unneeded member in CommentSema, add a test for the XML schema (the
schema already allowed multiple paragraphs in <ResultDiscussion>, but there
were no tests for that), fix HTML generation (it is not allowed to have <p>
inside <dl>).
llvm-svn: 184652
This change introduces a 'kind' attribute for the <Para> tag, that captures the
kind of the parent block command.
For example:
\todo Meow.
used to be just <Para>Meow.</Para>, but now it is
<Para kind="todo">Meow.</Para>
llvm-svn: 174216
fix any bad objectiveC syntax coming out of
DeclPrinter. This is on going. Also, introduce a new
PrintPolicy and use it as needed when declaration tag
is to be produced via DeclPrinter.
llvm-svn: 170606
use clang's formatter. Currently, formatter is used
to format declaration tags for xml comments. Since formatter
is in flux and its change will break several of the clang comment
tests, only a single tests is formatted using this facility.
Doug has reviewed and approved it for check-in.
llvm-svn: 170467
XML comment for declarations which pretty-prints
declaration. I had to XFAIL one test annotate-comments.cpp.
This test is currently unmaintainable as written.
Dmitri G., can you see what we can do about this test.
We should change this test such that adding a new tag does not wreck
havoc to the test.
llvm-svn: 166130
methods looking for documentation on a particular base
class inherited by any method that overrides the base class.
In case of redeclaration, as when objc method is defined
in the implementation, it also looks up for documentation
in class/class extension being redeclared.
llvm-svn: 165643
Now we have a list of all commands. This is a good thing in itself, but it
also enables us to easily implement typo correction for command names.
With this change we have objects that contain information about each command,
so it makes sense to resolve command name just once during lexing (currently we
store command names as strings and do a linear search every time some property
value is needed). Thus comment token and AST nodes were changed to contain a
command ID -- index into a tables of builtin and registered commands. Unknown
commands are registered during parsing and thus are also uniformly assigned an
ID. Using an ID instead of a StringRef is also a nice memory optimization
since ID is a small integer that fits into a common bitfield in Comment class.
This change implies that to get any information about a command (even a command
name) we need a CommandTraits object to resolve the command ID to CommandInfo*.
Currently a fresh temporary CommandTraits object is created whenever it is
needed since it does not have any state. But with this change it has state --
new commands can be registered, so a CommandTraits object was added to
ASTContext.
Also, in libclang CXComment has to be expanded to include a CXTranslationUnit
so that all functions working on comment AST nodes can get a CommandTraits
object. This breaks binary compatibility of CXComment APIs.
Now clang_FullComment_getAsXML(CXTranslationUnit TU, CXComment CXC) doesn't
need TU parameter anymore, so it was removed. This is a source-incompatible
change for this C API.
llvm-svn: 163540
The implementation also includes a Relax NG schema and tests for the schema
itself. The schema is used in c-index-test to verify that XML documents we
produce are valid. In order to do the validation, we add an optional libxml2
dependency for c-index-test.
Credits for CMake part go to Doug Gregor. Credits for Autoconf part go to Eric
Christopher. Thanks!
llvm-svn: 161431
Craig Topper