clang  16.0.0git
CommentBriefParser.cpp
Go to the documentation of this file.
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 
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 
48  L(L), Traits(Traits) {
49  // Get lookahead token.
50  ConsumeToken();
51 }
52 
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 
clang::comments::tok::text
@ text
Definition: CommentLexer.h:35
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::comments::Token::isNot
bool isNot(tok::TokenKind K) const LLVM_READONLY
Definition: CommentLexer.h:93
AttributeLangSupport::C
@ C
Definition: SemaDeclAttr.cpp:56
clang::comments::BriefParser::Parse
std::string Parse()
Return the best "brief description" we can find.
Definition: CommentBriefParser.cpp:53
clang::comments::CommandInfo
Information about a single command.
Definition: CommentCommandTraits.h:32
clang::comments::CommandInfo::IsBlockCommand
unsigned IsBlockCommand
True if this command is a block command (of any kind).
Definition: CommentCommandTraits.h:56
clang::comments::CommandTraits::getCommandInfo
const CommandInfo * getCommandInfo(StringRef Name) const
Definition: CommentCommandTraits.h:145
clang::comments::Token::getCommandID
unsigned getCommandID() const LLVM_READONLY
Definition: CommentLexer.h:120
clang::comments::CommandInfo::IsBriefCommand
unsigned IsBriefCommand
True if this command is introducing a brief documentation paragraph (\or an alias).
Definition: CommentCommandTraits.h:60
clang::comments::tok::at_command
@ at_command
Definition: CommentLexer.h:38
clang::comments::BriefParser::BriefParser
BriefParser(Lexer &L, const CommandTraits &Traits)
Definition: CommentBriefParser.cpp:47
clang::isWhitespace
LLVM_READONLY bool isWhitespace(unsigned char c)
Return true if this character is horizontal or vertical ASCII whitespace: ' ', '\t',...
Definition: CharInfo.h:93
CharInfo.h
CommentBriefParser.h
clang::comments::Token::getText
StringRef getText() const LLVM_READONLY
Definition: CommentLexer.h:98
clang::comments::Token::is
bool is(tok::TokenKind K) const LLVM_READONLY
Definition: CommentLexer.h:92
clang
Definition: CalledOnceCheck.h:17
Text
StringRef Text
Definition: Format.cpp:2716
clang::comments::CommandInfo::IsReturnsCommand
unsigned IsReturnsCommand
True if this command is \returns or an alias.
Definition: CommentCommandTraits.h:63
clang::comments::tok::eof
@ eof
Definition: CommentLexer.h:33
clang::comments::CommandTraits
This class provides information about commands that can be used in comments.
Definition: CommentCommandTraits.h:127
clang::comments::tok::backslash_command
@ backslash_command
Definition: CommentLexer.h:37
CommentCommandTraits.h
clang::comments::tok::newline
@ newline
Definition: CommentLexer.h:34
clang::comments::Lexer
Comment lexer.
Definition: CommentLexer.h:220