r181458 - documentation parsing. Patch to do typo correction for

Douglas Gregor dgregor at apple.com
Wed May 8 14:31:58 PDT 2013

On May 8, 2013, at 1:56 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> On Wed, May 8, 2013 at 11:13 PM, Douglas Gregor <dgregor at apple.com> wrote:
>> On May 8, 2013, at 12:42 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
>> On Wed, May 8, 2013 at 10:21 PM, Fariborz Jahanian <fjahanian at apple.com>
>> wrote:
>> void Lexer::lexCommentText(Token &T) {
>> @@ -354,8 +355,17 @@ void Lexer::lexCommentText(Token &T) {
>>        if (!Info) {
>>          formTokenWithChars(T, TokenPtr, tok::unknown_command);
>>          T.setUnknownCommandName(CommandName);
>> -          Diag(T.getLocation(), diag::warn_unknown_comment_command_name);
>> -          return;
>> +          if (Info = Traits.getTypoCorrectCommandInfo(CommandName)) {
>> +            StringRef CorrectedName = Info->Name;
>> +            SourceRange CommandRange(T.getLocation().getLocWithOffset(1),
>> +                                     T.getEndLocation());
>> +            Diag(T.getLocation(), diag::warn_correct_comment_command_name)
>> +              << CommandName << CorrectedName
>> +              << FixItHint::CreateReplacement(CommandRange, CorrectedName);
>> We recover by assuming that the user wanted this correction.  What if
>> they did not?..
>> That's the way Fix-Its are meant to work: we suggest something when we have
>> a high level of confidence in it, and continue on as if the user had typed
>> what we suggested.
> Yes, but this is a warning, so the comment AST is produced anyway.
> But comment parsing only produces warnings, there are no comment
> errors (yet? :)

Well, it'll be a less useful comment AST than if the correction was right.

>> (But I can only imagine such situation only for
>> external users who use comment parsing for something non-Doxygen.)
>> This is what -fcomment-block-comments=<blah> is for, right?
> Yes, that option too.  It registers block commands dynamically.  But
> we don't have an option to turn off built-in commands.  There is also
> a possibility that someone relies on all unknown commands being
> treated as inline commands (but we now start typo-correcting someone's
> command to a known block command).  Anyway, all this can be fixed by
> introducing two options in future (if someone needs it): an option to
> turn off built-in commands, and an option to register inline commands
> dynamically.

We're balancing the needs of the community that uses Doxygen/HeaderDoc against the needs of the community that uses other documentation commands with the same style (but different command names). Personally, I feel like the first first community is much, much larger, and that the second community can turn off -Wdocumentation or use -fcomment-block-comments=<blah>. I fully agree that it makes sense to have -fcomment-inline-commands=<blah> and (less important) something to turn off the builtin commands, to help the second community get more out of Clang.

	- Doug

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130508/94119a8a/attachment.html>

More information about the cfe-commits mailing list