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)
