We have a new policy in place making links to private resources
something we try to avoid in source and test files. Normally, we'd
organically switch to the new policy rather than make a sweeping change
across a project. However, Clang is in a somewhat special circumstance
currently: recently, I've had several new contributors run into rdar
links around test code which their patch was changing the behavior of.
This turns out to be a surprisingly bad experience, especially for
newer folks, for a handful of reasons: not understanding what the link
is and feeling intimidated by it, wondering whether their changes are
actually breaking something important to a downstream in some way,
having to hunt down strangers not involved with the patch to impose on
them for help, accidental pressure from asking for potentially private
IP to be made public, etc. Because folks run into these links entirely
by chance (through fixing bugs or working on new features), there's not
really a set of problematic links to focus on -- all of the links have
basically the same potential for causing these problems. As a result,
this is an omnibus patch to remove all such links.
This was not a mechanical change; it was done by manually searching for
rdar, radar, radr, and other variants to find all the various
problematic links. From there, I tried to retain or reword the
surrounding comments so that we would lose as little context as
possible. However, because most links were just a plain link with no
supporting context, the majority of the changes are simple removals.
Differential Review: https://reviews.llvm.org/D158071
This is a valid HTML5 tag. Previously it triggered a Clang error (`HTML start tag prematurely ended, expected attribute name or '>'`) since Clang was treating `/>` as a text token. This was happening because after lexing the closing quote (`"`) the lexer state was reset to "Normal" while the tag was not actually closed yet: `>` was not yet parsed at that point.
rdar://91464292
Differential Revision: https://reviews.llvm.org/D132932
That's required to support `\n`, but can also be used for other commands.
We already had the infrastructure in place to parse a varying number of
arguments, we simply needed to generalize it so that it would work not
only for block commands.
This should fix#55319.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D125429
The command traits have a member NumArgs for which all the parsing
infrastructure is in place, but no command was setting it to a value
other than 0. By doing so we get warnings when passing an empty
paragraph to \retval (the first argument is the return value, then comes
the description). We also take \xrefitem along for the ride, although as
the documentation states it's unlikely to be used directly.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D125422
This is consistent with the behavior of Doxygen, and allows users to
write strings with C escapes or document input/output formats containing
special characters (@ or \) without escaping them, which might be
confusing. For example, if a function wants to document its expected
input format as "user@host" it doesn't have to write user\@host instead,
which would look right in the documentation but confusing in the code.
Now users can just use double quotes (which they might do anyway).
This fixes a lot of false positives of -Wdocumentation-unknown-command,
but it could also fix issues with -Wdocumentation if the text triggers
an actual command.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D116190
Then we don't have to look into the declaration again. Also it's only
natural to collect this information alongside parameters and return
type, as it's also just a parameter in some sense.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D113690
We treat them as variables of course, though if they have function
pointer type we treat them as functions, i.e. allow parameter and return
value specifications. Just like VarDecls.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D111266
We were doing this already for type aliases, and it deduplicates the
code looking through aliases and pointers to find a function type. As
a side effect, this finds two warnings that we apparently missed before.
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D111264
Summary:
It's basically Doxygen's version of a link and can happen anywhere
inside of a paragraph. Fixes a bogus warning about empty paragraphs when
a parameter description starts with a link.
Reviewers: gribozavr2
Reviewed By: gribozavr2
Differential Revision: https://reviews.llvm.org/D75632
Summary:
Semantically they're the same thing, and it's important when the underlying
struct is anonymous.
There doesn't seem to be a problem attaching the same comment to multiple things
as it already happens with `/** doc */ int a, b;`
This affects an Index test but the results look better (name present, USR points
to the typedef).
Fixes https://github.com/clangd/clangd/issues/189
Reviewers: kadircet, lh123
Subscribers: ilya-biryukov, jkorous, arphaman, usaxena95, cfe-commits
Tags: #clang
Differential Revision: https://reviews.llvm.org/D70203
Summary:
The assertion happens when compiling with -Wdocumentation with variable declaration to a typedefed function pointer. I not too familiar with the ObjC syntax but first two tests assert without this patch.
Fixes https://bugs.llvm.org/show_bug.cgi?id=42844
Reviewers: gribozavr
Reviewed By: gribozavr
Subscribers: cfe-commits
Tags: #clang
Differential Revision: https://reviews.llvm.org/D66706
llvm-svn: 370677
Based on @davezarzycki remarks in D64696 improved the wording of the warning
message.
Differential Revision: https://reviews.llvm.org/D66700
Patch by Mark de Wever.
llvm-svn: 369873
...so that at least a preceding \param etc. that lacks a description gets a
-Wdocumentation warning (instead of erroneously treating the \retval ... text as
its paragraph).
Differential Revision: https://reviews.llvm.org/D66350
llvm-svn: 369345
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
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
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
Emit proper diagnostics when -Wdocumentation is used with constructs such as:
template<typename T>
using fn = int(T aaa, int ccc);
Previously clang wouldn't recognize the function and complain with
'comment that is not attached to a function declaration'.
Differential Revision: https://reviews.llvm.org/D23860
rdar://problem/27300695
llvm-svn: 279754
Give appropriate warnings with -Wdocumentation for @param comments
that refer to function aliases defined with 'using'. Very similar
to typedef's behavior. This does not add support for
TypeAliasTemplateDecl yet.
Differential Revision: https://reviews.llvm.org/D23783
rdar://problem/27300695
llvm-svn: 279662
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
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
