Commit Graph

38 Commits

Author SHA1 Message Date
Dmitri Gribenko 657330ee0e Adds a warning when an inline Doxygen comment has no argument
Summary:
It warns for for comments like
/** \pre \em */

where \em has no argument

This warning is enabled with the -Wdocumentation option.

Reviewers: gribozavr, rsmith

Reviewed By: gribozavr

Subscribers: cfe-commits

Tags: #clang

Differential Revision: https://reviews.llvm.org/D64696

Patch by Mark de Wever.

llvm-svn: 367809
2019-08-05 08:05:16 +00:00
Chandler Carruth 2946cd7010 Update the file headers across all of the LLVM projects in the monorepo
to reflect the new license.

We understand that people may be surprised that we're moving the header
entirely to discuss the new license. We checked this carefully with the
Foundation's lawyer and we believe this is the correct approach.

Essentially, all code in the project is now made available by the LLVM
project under our new license, so you will see that the license headers
include that license only. Some of our contributors have contributed
code under our old license, and accordingly, we have retained a copy of
our old license notice in the top-level files in each project and
repository.

llvm-svn: 351636
2019-01-19 08:50:56 +00:00
Reid Kleckner c6fbfd84ad Remove spurious assertion in -Wdocumentation
Some code in OpenCV uses interesting doxygen directives that make it so
we don't see any tokens inside a @note, despite there definitely being
non-whitespace characters there. The consistency check isn't needed.
ParagraphComment supports receiving an empty list of comments.

Fixes PR39007

llvm-svn: 343641
2018-10-02 22:23:27 +00:00
Alexander Shaposhnikov c937026e7e [cleanup] Remove excessive padding from TextTokenRetokenizer::Position
Reorder the fields of the struct TextTokenRetokenizer::Position to remove excessive padding.
Test plan: make -j8 check-clang

Differential revision: https://reviews.llvm.org/D24751

llvm-svn: 281995
2016-09-20 18:32:48 +00:00
Craig Topper 36250ad632 [C++11] Use 'nullptr'. AST edition.
llvm-svn: 208517
2014-05-12 05:36:57 +00:00
Dmitri Gribenko 1e50cbf366 Comment parsing: fix a bug where a line with whitespace between two paragraphs
would cause us to concatenate these paragraphs into a single one.

The no-op whitespace churn in test/Index test happened because these tests
don't use the correct approach for testing and are more strict than required
for they are testing.

llvm-svn: 189126
2013-08-23 18:03:40 +00:00
Dmitri Gribenko 44ebbd5436 Replace ArrayRef<T>() with None, now that we have an implicit ArrayRef constructor from None
Patch by Robert Wilhelm.

llvm-svn: 181139
2013-05-05 00:41:58 +00:00
Dmitri Gribenko c2c804d145 Comment parsing: simplify code. As a side effect, this also silences GCC's
-Wunitnitialized warning.

Patch by Rui Ueyama.

llvm-svn: 179794
2013-04-18 20:50:35 +00:00
Fariborz Jahanian f4ba35d809 doc parsing. Add @method and @callback for
checkings and few other refactoring/cleanup.
// rdar://13094352.

llvm-svn: 176509
2013-03-05 19:40:47 +00:00
Fariborz Jahanian 8a7a59226d doc parsing. We want to issue a strong warning when
an @function comment is not followed by a function decl.
// rdar://13094352

llvm-svn: 176468
2013-03-05 01:05:07 +00:00
Dmitri Gribenko bcf7f4d3bb Comment parsing: refactor handling of command markers in AST
* 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
2013-03-04 23:06:15 +00:00
Fariborz Jahanian e400cb70d4 Some refactoring in my patch on document
command source fidelity. // rdar://13066276

llvm-svn: 176401
2013-03-02 02:39:57 +00:00
Fariborz Jahanian d49963609d comment parsing. Keep the original command format
in AST for source fidelity and use it in diagnostics 
to refer to the original format. // rdar://13066276

llvm-svn: 176387
2013-03-01 22:51:30 +00:00
Dmitri Gribenko bcef3411cd Comment parsing: use CharInfo.h
This also gives us 0.2% speedup on '-fsyntax-only -Wdocumentation' time for
a testcase that consists of all Clang headers.

llvm-svn: 174810
2013-02-09 15:16:58 +00:00
Dmitri Gribenko 7146930591 Comment parsing: actually check for a block command after "\param x"
This fixes PR15068.

llvm-svn: 173539
2013-01-26 00:36:14 +00:00
Dmitri Gribenko c55c6fc6e3 Fix PR14591: Windows newlines in doxygen comments cause failed assertion in
TextDiagnostic

Patch by Janusz Chorko.

llvm-svn: 170566
2012-12-19 17:34:55 +00:00
Dmitri Gribenko 696d7226d6 Comment parsing: add a missing 'else'. Found by inspection.
No testcase because we were just building an extra AST node and eventually
throwing it away, so it did not affect correctness.

llvm-svn: 170563
2012-12-19 17:17:09 +00:00
Chandler Carruth 3a02247dc9 Sort all of Clang's files under 'lib', and fix up the broken headers
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
2012-12-04 09:13:33 +00:00
Dmitri Gribenko 76b91c3431 Documentation parsing: propely handle a lone '\endverbatim' and emit a warning.
We actually used to assert on this.

Thanks to NAKAMURA Takumi for noticing this!

llvm-svn: 168277
2012-11-18 00:30:31 +00:00
Dmitri Gribenko 9304d86329 Comment parsing: handle non-builtin commands correctly. After semantic
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
2012-09-11 19:22:03 +00:00
Dmitri Gribenko 7acbf00f96 Comment AST: TableGen'ize all command lists in CommentCommandTraits.cpp.
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
2012-09-10 20:32:42 +00:00
Dmitri Gribenko ca7f80ada0 Comment parsing: extract TableGen'able pieces into new CommandTraits class.
llvm-svn: 161548
2012-08-09 00:03:17 +00:00
Dmitri Gribenko 6297fa8a14 Comment parsing: fix crash on \tparam followed immediately by another block
command, for example: \tparam\brief.

llvm-svn: 161361
2012-08-06 23:48:44 +00:00
Dmitri Gribenko a9770ad820 Comment parser and sema: remove useless return values
llvm-svn: 161331
2012-08-06 19:03:12 +00:00
Dmitri Gribenko 34df220410 Comment parsing: add support for \tparam command on all levels.
The only caveat is renumbering CXCommentKind enum for aesthetic reasons -- this
breaks libclang binary compatibility, but should not be a problem since API is
so new.

This also fixes PR13372 as a side-effect.

llvm-svn: 161087
2012-07-31 22:37:06 +00:00
Dmitri Gribenko 1ba47ca4b5 Comment parser: don't crash on a completely empty \param followed by a block
command

llvm-svn: 160975
2012-07-30 18:05:28 +00:00
Dmitri Gribenko 35b0c09b6c Comment parsing: allow newlines between \param, direction specification (e.g.,
[in]), parameter name and description paragraph.

llvm-svn: 160682
2012-07-24 18:23:31 +00:00
Dmitri Gribenko 0a36302ae0 Comment parsing: couple TextTokenRetokenizer and comment parser together to
remove one of the two variable-length lookahead buffers.  Now retokenizer will
ask for more tokens when it needs them.

llvm-svn: 160680
2012-07-24 17:52:18 +00:00
Dmitri Gribenko 1bfd9dadda Move TextTokenRetokenizer from CommentLexer.h to CommentParser.cpp since it is
an implementation detail of the parser.

llvm-svn: 160679
2012-07-24 17:43:18 +00:00
Dmitri Gribenko 1c85d5b17d Comment parsing: retokenized text tokens are now pushed back in correct (not
reverse) order

llvm-svn: 160675
2012-07-24 16:10:47 +00:00
Dmitri Gribenko 66a00c765f Fix PR13411: Comment parsing: failed assertion on unterminated verbatim block.
The assertion was wrong in case we have a verbatim block without a closing
command.

Also add tests for closing command name in a verbatim block, since now it can
be empty in such cases.

llvm-svn: 160568
2012-07-20 20:18:53 +00:00
Dmitri Gribenko b03cc7e9f4 This fits into 80 columns without wrapping.
llvm-svn: 160453
2012-07-18 21:27:38 +00:00
Dmitri Gribenko e00ffc7bb8 Comment parsing: repaint the bikesched: rename 'HTML open tags' to 'HTML start tags' and 'HTML close tags' to 'HTML end tags' according to HTML spec.
llvm-svn: 160153
2012-07-13 00:44:24 +00:00
Dmitri Gribenko f26054f0fb Enable comment parsing and semantic analysis to emit diagnostics. A few
diagnostics implemented -- see testcases.

I created a new TableGen file for comment diagnostics,
DiagnosticCommentKinds.td, because comment diagnostics don't logically
fit into AST diagnostics file.  But I don't feel strongly about it.

This also implements support for self-closing HTML tags in comment
lexer and parser (for example, <br />).

In order to issue precise diagnostics CommentSema needs to know the
declaration the comment is attached to.  There is no easy way to find a decl by 
comment, so we match comments and decls in lockstep: after parsing one
declgroup we check if we have any new, not yet attached comments.  If we do --
then we do the usual comment-finding process.

It is interesting that this automatically handles trailing comments.
We pick up not only comments that precede the declaration, but also
comments that *follow* the declaration -- thanks to the lookahead in
the lexer: after parsing the declgroup we've consumed the semicolon
and looked ahead through comments.

Added -Wdocumentation-html flag for semantic HTML errors to allow the user to 
disable only HTML warnings (but not HTML parse errors, which we emit as
warnings in -Wdocumentation).

llvm-svn: 160078
2012-07-11 21:38:39 +00:00
Matt Beaumont-Gay 4106ea3b4e Sprinkle llvm_unreachable around to placate GCC's -Wreturn-type.
llvm-svn: 159860
2012-07-06 21:13:09 +00:00
Dmitri Gribenko bacb9f65a7 Stop using new[] on llvm::BumpPtrAllocator.
llvm-svn: 159833
2012-07-06 16:41:59 +00:00
Dmitri Gribenko 017b677737 CommentParser.cpp: remove unused variable.
llvm-svn: 159797
2012-07-06 01:14:58 +00:00
Dmitri Gribenko ec92531c29 Implement AST classes for comments, a real parser for Doxygen comments and a
very simple semantic analysis that just builds the AST; minor changes for lexer
to pick up source locations I didn't think about before.

Comments AST is modelled along the ideas of HTML AST: block and inline content.

* Block content is a paragraph or a command that has a paragraph as an argument
  or verbatim command.
* Inline content is placed within some block.  Inline content includes plain
  text, inline commands and HTML as tag soup.

llvm-svn: 159790
2012-07-06 00:28:32 +00:00