bazel syntax: delete StarlarkFunction.getStatements Clients cannot assume the representation of code is syntax trees; soon, it will be bytecode. Details: - added StarlarkFunction.getDocumentation method. - remove dead code from DocstringUtils collectDocstringLiterals, getNameAndDocstring, getAssignedVariableName, extractDocstring - DocstringUtils.parseDocstring now computes the indentation using a heuristic. - removed assertion from StarlarkFunctionCodecTest - rephrased assertion in PackageSerializationTest - remove function syntax from some obscure log messages PiperOrigin-RevId: 290084502
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/StarlarkFunction.java b/src/main/java/com/google/devtools/build/lib/syntax/StarlarkFunction.java index bd53793..b9bf93b 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/StarlarkFunction.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/StarlarkFunction.java
@@ -15,6 +15,7 @@ import com.google.common.collect.ImmutableList; import com.google.devtools.build.lib.events.Location; +import javax.annotation.Nullable; /** A StarlarkFunction is the function value created by a Starlark {@code def} statement. */ public final class StarlarkFunction extends BaseFunction { @@ -69,11 +70,21 @@ return name; } - /** @deprecated Do not assume function values are represented as syntax trees. */ - // TODO(adonovan): the only non-test use is to obtain the function's doc string. Add API for that. - @Deprecated - public ImmutableList<Statement> getStatements() { - return statements; + /** Returns the value denoted by the function's doc string literal, or null if absent. */ + @Nullable + public String getDocumentation() { + if (statements.isEmpty()) { + return null; + } + Statement first = statements.get(0); + if (!(first instanceof ExpressionStatement)) { + return null; + } + Expression expr = ((ExpressionStatement) first).getExpression(); + if (!(expr instanceof StringLiteral)) { + return null; + } + return ((StringLiteral) expr).getValue(); } public Module getModule() {
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/StringLiteral.java b/src/main/java/com/google/devtools/build/lib/syntax/StringLiteral.java index bee563d..d38f85d 100644 --- a/src/main/java/com/google/devtools/build/lib/syntax/StringLiteral.java +++ b/src/main/java/com/google/devtools/build/lib/syntax/StringLiteral.java
@@ -23,16 +23,18 @@ /** Syntax node for a string literal. */ public final class StringLiteral extends Expression { - String value; - public String getValue() { - return value; - } + private final String value; StringLiteral(String value) { this.value = value; } + /** Returns the value denoted by the string literal */ + public String getValue() { + return value; + } + @Override public void accept(NodeVisitor visitor) { visitor.visit(this);
diff --git a/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java b/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java index 06fe769..02ed1e0 100644 --- a/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java +++ b/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
@@ -58,6 +58,8 @@ import com.google.devtools.build.lib.syntax.BaseFunction; import com.google.devtools.build.lib.syntax.EvalException; import com.google.devtools.build.lib.syntax.EvalUtils; +import com.google.devtools.build.lib.syntax.Expression; +import com.google.devtools.build.lib.syntax.ExpressionStatement; import com.google.devtools.build.lib.syntax.LoadStatement; import com.google.devtools.build.lib.syntax.Module; import com.google.devtools.build.lib.syntax.Mutability; @@ -122,7 +124,6 @@ import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.ProviderInfo; import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.RuleInfo; import com.google.devtools.common.options.OptionsParser; -import com.google.devtools.skylark.common.DocstringUtils; import java.io.BufferedOutputStream; import java.io.FileOutputStream; import java.io.IOException; @@ -395,10 +396,12 @@ private static String getModuleDoc(StarlarkFile buildFileAST) { ImmutableList<Statement> fileStatements = buildFileAST.getStatements(); if (!fileStatements.isEmpty()) { - Statement moduleComment = fileStatements.get(0); - StringLiteral moduleDocLiteral = DocstringUtils.getStringLiteral(moduleComment); - if (moduleDocLiteral != null) { - return moduleDocLiteral.getValue(); + Statement stmt = fileStatements.get(0); + if (stmt instanceof ExpressionStatement) { + Expression expr = ((ExpressionStatement) stmt).getExpression(); + if (expr instanceof StringLiteral) { + return ((StringLiteral) expr).getValue(); + } } } return "";
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java b/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java index efe1a8e..712a6ca 100644 --- a/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java +++ b/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java
@@ -21,7 +21,6 @@ import com.google.devtools.build.lib.syntax.Printer; import com.google.devtools.build.lib.syntax.Printer.BasePrinter; import com.google.devtools.build.lib.syntax.StarlarkFunction; -import com.google.devtools.build.lib.syntax.StringLiteral; import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.FunctionParamInfo; import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.StarlarkFunctionInfo; import com.google.devtools.skylark.common.DocstringUtils; @@ -41,24 +40,21 @@ * @param functionName the name of the function in the target scope. (Note this is not necessarily * the original exported function name; the function may have been renamed in the target * Starlark file's scope) - * @param userDefinedFunction the raw function object + * @param fn the function object * @throws com.google.devtools.build.skydoc.rendering.DocstringParseException if the function's * docstring is malformed */ - public static StarlarkFunctionInfo fromNameAndFunction( - String functionName, StarlarkFunction userDefinedFunction) throws DocstringParseException { + public static StarlarkFunctionInfo fromNameAndFunction(String functionName, StarlarkFunction fn) + throws DocstringParseException { String functionDescription = ""; Map<String, String> paramNameToDocMap = Maps.newLinkedHashMap(); - StringLiteral docStringLiteral = - DocstringUtils.extractDocstring(userDefinedFunction.getStatements()); - - if (docStringLiteral != null) { + String doc = fn.getDocumentation(); + if (doc != null) { List<DocstringParseError> parseErrors = Lists.newArrayList(); - DocstringInfo docstringInfo = DocstringUtils.parseDocstring(docStringLiteral, parseErrors); + DocstringInfo docstringInfo = DocstringUtils.parseDocstring(doc, parseErrors); if (!parseErrors.isEmpty()) { - throw new DocstringParseException( - functionName, userDefinedFunction.getLocation(), parseErrors); + throw new DocstringParseException(functionName, fn.getLocation(), parseErrors); } functionDescription += docstringInfo.getSummary(); if (!docstringInfo.getSummary().isEmpty() && !docstringInfo.getLongDescription().isEmpty()) { @@ -69,7 +65,7 @@ paramNameToDocMap.put(paramDoc.getParameterName(), paramDoc.getDescription()); } } - List<FunctionParamInfo> paramsInfo = parameterInfos(userDefinedFunction, paramNameToDocMap); + List<FunctionParamInfo> paramsInfo = parameterInfos(fn, paramNameToDocMap); return StarlarkFunctionInfo.newBuilder() .setFunctionName(functionName) .setDocString(functionDescription)