implements PLN-0097

This commit is contained in:
2026-07-15 07:08:11 +01:00
parent aeea8ca900
commit d680504c31
5 changed files with 143 additions and 16 deletions
@@ -587,7 +587,7 @@ public final class PbsEditorialSupportService {
formatCallableDetails(methods),
receiverType.name(),
signaturesFromCallables(methods),
""));
documentationFromCallables(methods)));
}
}
if (receiverType.kind() == Kind.SERVICE || receiverType.kind() == Kind.CONTRACT) {
@@ -602,7 +602,7 @@ public final class PbsEditorialSupportService {
formatCallableDetails(signatures),
receiverType.name(),
signaturesFromCallables(signatures),
""));
documentationFromCallables(signatures)));
}
}
return Optional.empty();
@@ -663,7 +663,7 @@ public final class PbsEditorialSupportService {
detail,
topDeclSymbol.origin(),
signatures,
"");
documentationFromTopDecl(topDeclSymbol.decl()));
}
private PbsEditorialResolvedSymbol constructorSymbolFromTopDecl(
@@ -678,7 +678,68 @@ public final class PbsEditorialSupportService {
detail,
topDeclSymbol.origin(),
signatures,
"");
documentationFromTopDecl(topDeclSymbol.decl()));
}
private String documentationFromCallables(final List<CallableSymbol> callables) {
for (final var callable : callables) {
if (!callable.documentation().isBlank()) {
return callable.documentation();
}
}
return "";
}
private String documentationFromTopDecl(final PbsAst.TopDecl topDecl) {
return documentationFromAttributes(attributesOf(topDecl));
}
private ReadOnlyList<PbsAst.Attribute> attributesOf(final PbsAst.TopDecl topDecl) {
if (topDecl instanceof PbsAst.FunctionDecl functionDecl) {
return functionDecl.attributes();
}
if (topDecl instanceof PbsAst.StructDecl structDecl) {
return structDecl.attributes();
}
if (topDecl instanceof PbsAst.BuiltinTypeDecl builtinTypeDecl) {
return builtinTypeDecl.attributes();
}
if (topDecl instanceof PbsAst.ServiceDecl serviceDecl) {
return serviceDecl.attributes();
}
if (topDecl instanceof PbsAst.HostDecl hostDecl) {
return hostDecl.attributes();
}
if (topDecl instanceof PbsAst.ContractDecl contractDecl) {
return contractDecl.attributes();
}
if (topDecl instanceof PbsAst.CallbackDecl callbackDecl) {
return callbackDecl.attributes();
}
if (topDecl instanceof PbsAst.EnumDecl enumDecl) {
return enumDecl.attributes();
}
if (topDecl instanceof PbsAst.ErrorDecl errorDecl) {
return errorDecl.attributes();
}
if (topDecl instanceof PbsAst.ConstDecl constDecl) {
return constDecl.attributes();
}
return ReadOnlyList.empty();
}
private String documentationFromAttributes(final ReadOnlyList<PbsAst.Attribute> attributes) {
for (final var attribute : attributes) {
if (!"Doc".equals(attribute.name()) || attribute.arguments().isEmpty()) {
continue;
}
final var argument = attribute.arguments().getFirst();
if (!"markdown".equals(argument.name()) || !(argument.value() instanceof PbsAst.AttributeDocTextBlockValue docValue)) {
continue;
}
return p.studio.compiler.pbs.PbsDocumentationTextBlockNormalizer.normalizeLexeme(docValue.value());
}
return "";
}
private PbsEditorialCompletionCandidate completionFromTopDecl(final TopDeclSymbol topDeclSymbol) {
@@ -146,7 +146,8 @@ final class PbsFlowSemanticSupport {
List<CallableParameter> parameters,
List<TypeView> inputTypes,
TypeView outputType,
Span span) {
Span span,
String documentation) {
}
record CallableParameter(
@@ -282,7 +283,8 @@ final class PbsFlowSemanticSupport {
method.returnKind(),
method.returnType(),
method.resultErrorType(),
method.span()));
method.span(),
documentationFromAttributes(method.attributes())));
}
structs.put(structDecl.name(), new StructInfo(fields, methods));
return;
@@ -306,7 +308,8 @@ final class PbsFlowSemanticSupport {
signature.returnKind(),
signature.returnType(),
signature.resultErrorType(),
signature.span()));
signature.span(),
documentationFromAttributes(signature.attributes())));
}
structs.put(builtinTypeDecl.name(), new StructInfo(fields, methods));
return;
@@ -321,7 +324,8 @@ final class PbsFlowSemanticSupport {
method.returnKind(),
method.returnType(),
method.resultErrorType(),
method.span()));
method.span(),
documentationFromAttributes(method.attributes())));
}
services.put(serviceDecl.name(), new ServiceInfo(methods));
serviceSingletons.put(serviceDecl.name(), TypeView.service(serviceDecl.name()));
@@ -337,7 +341,8 @@ final class PbsFlowSemanticSupport {
signature.returnKind(),
signature.returnType(),
signature.resultErrorType(),
signature.span()));
signature.span(),
documentationFromAttributes(signature.attributes())));
}
// Host owners are value singletons with callable members, same access shape as services.
services.put(hostDecl.name(), new ServiceInfo(methods));
@@ -354,7 +359,8 @@ final class PbsFlowSemanticSupport {
signature.returnKind(),
signature.returnType(),
signature.resultErrorType(),
signature.span()));
signature.span(),
documentationFromAttributes(signature.attributes())));
}
contracts.put(contractDecl.name(), new ContractInfo(methods));
return;
@@ -367,7 +373,8 @@ final class PbsFlowSemanticSupport {
functionDecl.returnKind(),
functionDecl.returnType(),
functionDecl.resultErrorType(),
functionDecl.span()));
functionDecl.span(),
documentationFromAttributes(functionDecl.attributes())));
return;
}
if (topDecl instanceof PbsAst.CallbackDecl(
@@ -381,7 +388,8 @@ final class PbsFlowSemanticSupport {
returnKind,
returnType,
resultErrorType,
span);
span,
"");
callbacks.put(name, new CallbackSignature(symbol.inputTypes(), symbol.outputType()));
return;
}
@@ -478,7 +486,8 @@ final class PbsFlowSemanticSupport {
final PbsAst.ReturnKind returnKind,
final PbsAst.TypeRef returnType,
final PbsAst.TypeRef resultErrorType,
final Span span) {
final Span span,
final String documentation) {
final var input = new ArrayList<TypeView>(parameters.size());
final var semanticParameters = new ArrayList<CallableParameter>(parameters.size());
for (int index = 0; index < parameters.size(); index += 1) {
@@ -491,7 +500,21 @@ final class PbsFlowSemanticSupport {
type,
parameter.span()));
}
return new CallableSymbol(name, semanticParameters, input, callableReturn(returnKind, returnType, resultErrorType), span);
return new CallableSymbol(name, semanticParameters, input, callableReturn(returnKind, returnType, resultErrorType), span, documentation);
}
private String documentationFromAttributes(final ReadOnlyList<PbsAst.Attribute> attributes) {
for (final var attribute : attributes) {
if (!"Doc".equals(attribute.name()) || attribute.arguments().isEmpty()) {
continue;
}
final var argument = attribute.arguments().getFirst();
if (!"markdown".equals(argument.name()) || !(argument.value() instanceof PbsAst.AttributeDocTextBlockValue docValue)) {
continue;
}
return p.studio.compiler.pbs.PbsDocumentationTextBlockNormalizer.normalizeLexeme(docValue.value());
}
return "";
}
private TypeView callableReturn(
@@ -123,6 +123,49 @@ final class PbsEditorialSupportServiceTest {
assertEquals("Input", hostMethodHover.origin());
}
@Test
void shouldExposeDocMetadataOnTopLevelSymbolHover() {
final var source = """
[Doc(markdown = \"""
Runs the program.
- no parameters
\""")]
fn run() -> void { return; }
""";
final var ast = parseOrdinary(source);
final var hover = requireHover(source, ast, ReadOnlyList.empty(), "run");
assertEquals(PbsEditorialSymbolKind.FUNCTION, hover.kind());
assertEquals("Runs the program.\n\n- no parameters", hover.documentation());
}
@Test
void shouldExposeDocMetadataOnMemberHover() {
final var source = """
import { Gfx } from @sdk:gfx;
fn main() -> void {
Gfx.draw_pixel(1, 2, 3);
}
""";
final var ast = parseOrdinary(source);
final var supplementalTopDecls = supplementalTopDecls("""
declare host Gfx {
[Doc(markdown = \"""
Draws a single pixel.
\""")]
fn draw_pixel(x: int, y: int, color: int) -> void;
}
""");
final var hover = requireHover(source, ast, supplementalTopDecls, "draw_pixel");
assertEquals(PbsEditorialSymbolKind.METHOD, hover.kind());
assertEquals("Draws a single pixel.", hover.documentation());
}
@Test
void shouldResolveSignatureHelpForFunctionMethodAndConstructorCalls() {
final var source = """