Skip to content

Commit 51baa57

Browse files
DougGregorDougGregor
committed
[Code completion] Add doc comments for function builder build functions
Add brief documentation comments to each of the code completions produced for a build* function in a code completion.
1 parent 20ab640 commit 51baa57

File tree

4 files changed

+67
-15
lines changed

4 files changed

+67
-15
lines changed

‎include/swift/IDE/CodeCompletion.h

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -640,11 +640,13 @@ class CodeCompletionResult {
640640
CodeCompletionString *CompletionString,
641641
ExpectedTypeRelation TypeDistance,
642642
CodeCompletionOperatorKind KnownOperatorKind =
643-
CodeCompletionOperatorKind::None)
643+
CodeCompletionOperatorKind::None,
644+
StringRef BriefDocComment = StringRef())
644645
: Kind(Kind), KnownOperatorKind(unsigned(KnownOperatorKind)),
645646
SemanticContext(unsigned(SemanticContext)), NotRecommended(false),
646647
NotRecReason(NotRecommendedReason::NoReason),
647648
NumBytesToErase(NumBytesToErase), CompletionString(CompletionString),
649+
BriefDocComment(BriefDocComment),
648650
TypeDistance(TypeDistance) {
649651
assert(Kind != Declaration && "use the other constructor");
650652
assert(CompletionString);
@@ -664,12 +666,13 @@ class CodeCompletionResult {
664666
SemanticContextKind SemanticContext,
665667
unsigned NumBytesToErase,
666668
CodeCompletionString *CompletionString,
667-
ExpectedTypeRelation TypeDistance)
669+
ExpectedTypeRelation TypeDistance,
670+
StringRef BriefDocComment = StringRef())
668671
: Kind(Keyword), KnownOperatorKind(0),
669672
SemanticContext(unsigned(SemanticContext)), NotRecommended(false),
670673
NotRecReason(NotRecommendedReason::NoReason),
671674
NumBytesToErase(NumBytesToErase), CompletionString(CompletionString),
672-
TypeDistance(TypeDistance) {
675+
BriefDocComment(BriefDocComment), TypeDistance(TypeDistance) {
673676
assert(CompletionString);
674677
AssociatedKind = static_cast<unsigned>(Kind);
675678
IsSystem = 0;

‎lib/IDE/CodeCompletion.cpp

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1345,13 +1345,17 @@ CodeCompletionResult *CodeCompletionResultBuilder::takeResult() {
13451345

13461346
case CodeCompletionResult::ResultKind::Keyword:
13471347
return new (*Sink.Allocator)
1348-
CodeCompletionResult(KeywordKind, SemanticContext, NumBytesToErase,
1349-
CCS, ExpectedTypeRelation);
1348+
CodeCompletionResult(
1349+
KeywordKind, SemanticContext, NumBytesToErase,
1350+
CCS, ExpectedTypeRelation,
1351+
copyString(*Sink.Allocator, BriefDocComment));
13501352

13511353
case CodeCompletionResult::ResultKind::BuiltinOperator:
13521354
case CodeCompletionResult::ResultKind::Pattern:
13531355
return new (*Sink.Allocator) CodeCompletionResult(
1354-
Kind, SemanticContext, NumBytesToErase, CCS, ExpectedTypeRelation);
1356+
Kind, SemanticContext, NumBytesToErase, CCS, ExpectedTypeRelation,
1357+
CodeCompletionOperatorKind::None,
1358+
copyString(*Sink.Allocator, BriefDocComment));
13551359

13561360
case CodeCompletionResult::ResultKind::Literal:
13571361
assert(LiteralKind.hasValue());
@@ -5136,6 +5140,45 @@ class CompletionOverrideLookup : public swift::VisibleDeclConsumer {
51365140
}
51375141
}
51385142

5143+
static StringRef getFunctionBuilderDocComment(
5144+
FunctionBuilderBuildFunction function) {
5145+
switch (function) {
5146+
case FunctionBuilderBuildFunction::BuildArray:
5147+
return "Enables support for..in loops in a function builder by "
5148+
"combining the results of all iterations into a single result";
5149+
5150+
case FunctionBuilderBuildFunction::BuildBlock:
5151+
return "Required by every function builder to build combined results "
5152+
"from statement blocks";
5153+
5154+
case FunctionBuilderBuildFunction::BuildEitherFirst:
5155+
return "With buildEither(second:), enables support for 'if-else' and "
5156+
"'switch' statements by folding conditional results into a single "
5157+
"result";
5158+
5159+
case FunctionBuilderBuildFunction::BuildEitherSecond:
5160+
return "With buildEither(first:), enables support for 'if-else' and "
5161+
"'switch' statements by folding conditional results into a single "
5162+
"result";
5163+
5164+
case FunctionBuilderBuildFunction::BuildExpression:
5165+
return "If declared, provides contextual type information for statement "
5166+
"expressions to translate them into partial results";
5167+
5168+
case FunctionBuilderBuildFunction::BuildFinalResult:
5169+
return "If declared, this will be called on the partial result from the "
5170+
"outermost block statement to produce the final returned result";
5171+
5172+
case FunctionBuilderBuildFunction::BuildLimitedAvailability:
5173+
return "If declaration, this will be called on the partial result of "
5174+
"an 'if #available' block to allow the function builder to erase "
5175+
"type information";
5176+
5177+
case FunctionBuilderBuildFunction::BuildOptional:
5178+
return "Enables support for `if` statements that do not have an `else`";
5179+
}
5180+
}
5181+
51395182
void addFunctionBuilderBuildCompletion(
51405183
NominalTypeDecl *builder, Type componentType,
51415184
FunctionBuilderBuildFunction function) {
@@ -5165,6 +5208,7 @@ class CompletionOverrideLookup : public swift::VisibleDeclConsumer {
51655208
}
51665209
Builder.addTextChunk(declStringWithoutFunc);
51675210
Builder.addBraceStmtWithCursor();
5211+
Builder.setBriefDocComment(getFunctionBuilderDocComment(function));
51685212
}
51695213

51705214
/// Add completions for the various "build" functions in a function builder.

‎lib/IDE/CodeCompletionResultBuilder.h

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ class CodeCompletionResultBuilder {
9292
bool IsNotRecommended = false;
9393
CodeCompletionResult::NotRecommendedReason NotRecReason =
9494
CodeCompletionResult::NotRecommendedReason::NoReason;
95+
StringRef BriefDocComment = StringRef();
9596

9697
void addChunkWithText(CodeCompletionString::Chunk::ChunkKind Kind,
9798
StringRef Text);
@@ -446,6 +447,10 @@ class CodeCompletionResultBuilder {
446447
addWhitespace(space);
447448
getLastChunk().setIsAnnotation();
448449
}
450+
451+
void setBriefDocComment(StringRef comment) {
452+
BriefDocComment = comment;
453+
}
449454
};
450455

451456
} // namespace ide

‎test/IDE/complete_function_builder.swift

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// RUN: %target-swift-ide-test -code-completion -source-filename %s -code-completion-token=IN_CLOSURE_TOP | %FileCheck %s -check-prefix=IN_CLOSURE_TOP
22
// RUN: %target-swift-ide-test -code-completion -source-filename %s -code-completion-token=IN_CLOSURE_NONTOP | %FileCheck %s -check-prefix=IN_CLOSURE_TOP
33
// RUN: %target-swift-ide-test -code-completion -source-filename %s -code-completion-token=IN_CLOSURE_COLOR_CONTEXT | %FileCheck %s -check-prefix=IN_CLOSURE_COLOR_CONTEXT
4-
// RUN: %target-swift-ide-test -code-completion -source-filename %s -code-completion-token=IN_FUNCTION_BUILDER_DECL | %FileCheck %s -check-prefix=IN_FUNCTION_BUILDER_DECL
4+
// RUN: %target-swift-ide-test -code-completion -source-filename %s -code-completion-token=IN_FUNCTION_BUILDER_DECL -code-completion-comments=true | %FileCheck %s -check-prefix=IN_FUNCTION_BUILDER_DECL
55

66
struct Tagged<Tag, Entity> {
77
let tag: Tag
@@ -103,12 +103,12 @@ struct AnyBuilder {
103103
}
104104

105105
// IN_FUNCTION_BUILDER_DECL: Begin completions, 8 items
106-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildBlock(_ components: Any...) -> Any { {|}; name=buildBlock(_ components: Any...) -> Any {
107-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildExpression(_ expression: <#Expression#>) -> Any { {|}; name=buildExpression(_ expression: <#Expression#>) -> Any {
108-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildOptional(_ component: Any?) -> Any { {|}; name=buildOptional(_ component: Any?) -> Any {
109-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildEither(first component: Any) -> Any { {|}; name=buildEither(first component: Any) -> Any {
110-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildEither(second component: Any) -> Any { {|}; name=buildEither(second component: Any) -> Any {
111-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildArray(_ components: [Any]) -> Any { {|}; name=buildArray(_ components: [Any]) -> Any {
112-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildLimitedAvailability(_ component: Any) -> Any { {|}; name=buildLimitedAvailability(_ component: Any) -> Any {
113-
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildFinalResult(_ component: Any) -> <#Result#> {|}; name=buildFinalResult(_ component: Any) -> <#Result#>
106+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildBlock(_ components: Any...) -> Any { {|}; name=buildBlock(_ components: Any...) -> Any {; comment=Required by every
107+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildExpression(_ expression: <#Expression#>) -> Any { {|}; name=buildExpression(_ expression: <#Expression#>) -> Any {; comment=
108+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildOptional(_ component: Any?) -> Any { {|}; name=buildOptional(_ component: Any?) -> Any {; comment=
109+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildEither(first component: Any) -> Any { {|}; name=buildEither(first component: Any) -> Any {; comment=
110+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildEither(second component: Any) -> Any { {|}; name=buildEither(second component: Any) -> Any {; comment=
111+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildArray(_ components: [Any]) -> Any { {|}; name=buildArray(_ components: [Any]) -> Any {; comment=
112+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildLimitedAvailability(_ component: Any) -> Any { {|}; name=buildLimitedAvailability(_ component: Any) -> Any {; comment=
113+
// IN_FUNCTION_BUILDER_DECL: Pattern/CurrNominal: buildFinalResult(_ component: Any) -> <#Result#> {|}; name=buildFinalResult(_ component: Any) -> <#Result#>; comment=
114114
// IN_FUNCTION_BUILDER_DECL: End completions

0 commit comments

Comments
 (0)