function/block pointer properties
The commit r300981 allowed @param/@return commands for function/block
pointer property declarations. This meant that -Wdocumentation started warning
about @return that was used to document properties whose function/block type
returned void. However, prior to that commit, we allowed @return for all
property declarations, because it can be used to document the value that's
returned by the property getter. This commit restores the previous behaviour:
now the @return command can be used to document all properties without warnings.
rdar://24978538
llvm-svn: 301402
that have a function/block pointer type
This commit improves the -Wdocumentation warning by making sure that @param and
@returns commands won't trigger warnings when used for fields, variables,
or properties whose type is a function/block pointer type. The
function/block pointer type must be specified directly with the declaration,
and when a typedef is used the warning is still emitted.
In the future we might also want to handle the std::function type as well.
rdar://24978538
llvm-svn: 300981
Add the "explicit" specifier to the single-argument constructor of
SimpleTypoCorrector. Reorder the fields to remove excessive padding (8 bytes).
Patch by Alexander Shaposhnikov!
llvm-svn: 279946
Since the community says that a blacklist is not good enough, and I don't have
enough time now to implement a proper whitelist, let's just remove the
attribute validation.
But, nevertheless, we can still communicate in the generated XML if our parser
found an issue with the HTML. But this bit is best-effort and is specifically
called out in the schema as such.
llvm-svn: 207712
through to the output even if the input comment comes from an untrusted source
Attribute filtering is currently based on a blacklist, which right now includes
all event handler attributes (they contain JavaScipt code). It should be
switched to a whitelist, but going over all of the HTML5 spec requires a
significant amount of time.
llvm-svn: 206882
(comment without a decl).
I think this can not happen during normal compilation with -Wdocumentation,
only while using Clang APIs to parse comments outside of a source file.
Based on a patch by Olivier Goffart.
llvm-svn: 200230
A return type is the declared or deduced part of the function type specified in
the declaration.
A result type is the (potentially adjusted) type of the value of an expression
that calls the function.
Rule of thumb:
* Declarations have return types and parameters.
* Expressions have result types and arguments.
llvm-svn: 200082
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
* Use the term 'command marker', because the semantics of 'backslash' and 'at'
commands are the same. (Talking about 'at commands' makes them look like a
special entity.)
* Sink the flag down into bitfields, reducing the size of AST nodes.
* Change the flag into an enum for clarity. Boolean function parameters are
not very clear.
* Add unittests for new tok::at_command tokens.
llvm-svn: 176461
uncovered.
This required manually correcting all of the incorrect main-module
headers I could find, and running the new llvm/utils/sort_includes.py
script over the files.
I also manually added quite a few missing headers that were uncovered by
shuffling the order or moving headers up to be main-module-headers.
llvm-svn: 169237
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
deprecation attribute ('deprecated', 'availability' or 'unavailable').
This warning is under a separate flag, -Wdocumentation-deprecated-sync, so it
can be turned off easily while leaving other -Wdocumentation warnings on.
llvm-svn: 164467
should be fine to use it without further explanations in the attached
paragraph, so the warning about empty paragraph was turned off for it.
llvm-svn: 163836
analysis registers a command, it becomes a "known" command for the lexer, since
it has an ID. Having this freedom of choice to register a command is a good
thing since BriefParser does not need this.
But the parser should still invoke the correct semantic analysis method
(actOnUnknownCommand) in this case.
llvm-svn: 163646
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
Alex Lorenz