llvm-project

1
//===--- CommentBriefParser.cpp - Dumb comment parser ---------------------===//
2
//
3
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4
// See https://llvm.org/LICENSE.txt for license information.
5
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6
//
7
//===----------------------------------------------------------------------===//
8

9
#include "clang/AST/CommentBriefParser.h"
10
#include "clang/AST/CommentCommandTraits.h"
11
#include "clang/Basic/CharInfo.h"
12

13
namespace clang {
14
namespace comments {
15

16
namespace {
17

18
/// Convert all whitespace into spaces, remove leading and trailing spaces,
19
/// compress multiple spaces into one.
20
void cleanupBrief(std::string &S) {
21
  bool PrevWasSpace = true;
22
  std::string::iterator O = S.begin();
23
  for (std::string::iterator I = S.begin(), E = S.end();
24
       I != E; ++I) {
25
    const char C = *I;
26
    if (clang::isWhitespace(C)) {
27
      if (!PrevWasSpace) {
28
        *O++ = ' ';
29
        PrevWasSpace = true;
30
      }
31
    } else {
32
      *O++ = C;
33
      PrevWasSpace = false;
34
    }
35
  }
36
  if (O != S.begin() && *(O - 1) == ' ')
37
    --O;
38

39
  S.resize(O - S.begin());
40
}
41

42
bool isWhitespace(StringRef Text) {
43
  return llvm::all_of(Text, clang::isWhitespace);
44
}
45
} // unnamed namespace
46

47
BriefParser::BriefParser(Lexer &L, const CommandTraits &Traits) :
48
    L(L), Traits(Traits) {
49
  // Get lookahead token.
50
  ConsumeToken();
51
}
52

53
std::string BriefParser::Parse() {
54
  std::string FirstParagraphOrBrief;
55
  std::string ReturnsParagraph;
56
  bool InFirstParagraph = true;
57
  bool InBrief = false;
58
  bool InReturns = false;
59

60
  while (Tok.isNot(tok::eof)) {
61
    if (Tok.is(tok::text)) {
62
      if (InFirstParagraph || InBrief)
63
        FirstParagraphOrBrief += Tok.getText();
64
      else if (InReturns)
65
        ReturnsParagraph += Tok.getText();
66
      ConsumeToken();
67
      continue;
68
    }
69

70
    if (Tok.is(tok::backslash_command) || Tok.is(tok::at_command)) {
71
      const CommandInfo *Info = Traits.getCommandInfo(Tok.getCommandID());
72
      if (Info->IsBriefCommand) {
73
        FirstParagraphOrBrief.clear();
74
        InBrief = true;
75
        ConsumeToken();
76
        continue;
77
      }
78
      if (Info->IsReturnsCommand) {
79
        InReturns = true;
80
        InBrief = false;
81
        InFirstParagraph = false;
82
        ReturnsParagraph += "Returns ";
83
        ConsumeToken();
84
        continue;
85
      }
86
      // Block commands implicitly start a new paragraph.
87
      if (Info->IsBlockCommand) {
88
        // We found an implicit paragraph end.
89
        InFirstParagraph = false;
90
        if (InBrief)
91
          break;
92
      }
93
    }
94

95
    if (Tok.is(tok::newline)) {
96
      if (InFirstParagraph || InBrief)
97
        FirstParagraphOrBrief += ' ';
98
      else if (InReturns)
99
        ReturnsParagraph += ' ';
100
      ConsumeToken();
101

102
      // If the next token is a whitespace only text, ignore it.  Thus we allow
103
      // two paragraphs to be separated by line that has only whitespace in it.
104
      //
105
      // We don't need to add a space to the parsed text because we just added
106
      // a space for the newline.
107
      if (Tok.is(tok::text)) {
108
        if (isWhitespace(Tok.getText()))
109
          ConsumeToken();
110
      }
111

112
      if (Tok.is(tok::newline)) {
113
        ConsumeToken();
114
        // We found a paragraph end.  This ends the brief description if
115
        // \command or its equivalent was explicitly used.
116
        // Stop scanning text because an explicit \paragraph is the
117
        // preferred one.
118
        if (InBrief)
119
          break;
120
        // End first paragraph if we found some non-whitespace text.
121
        if (InFirstParagraph && !isWhitespace(FirstParagraphOrBrief))
122
          InFirstParagraph = false;
123
        // End the \\returns paragraph because we found the paragraph end.
124
        InReturns = false;
125
      }
126
      continue;
127
    }
128

129
    // We didn't handle this token, so just drop it.
130
    ConsumeToken();
131
  }
132

133
  cleanupBrief(FirstParagraphOrBrief);
134
  if (!FirstParagraphOrBrief.empty())
135
    return FirstParagraphOrBrief;
136

137
  cleanupBrief(ReturnsParagraph);
138
  return ReturnsParagraph;
139
}
140

141
} // end namespace comments
142
} // end namespace clang
143

144

145