Refactor UserDefinedFunctionInfo into a proto.
PiperOrigin-RevId: 252418282
diff --git a/src/main/java/com/google/devtools/build/skydoc/BUILD b/src/main/java/com/google/devtools/build/skydoc/BUILD
index f34fda2..453b998 100644
--- a/src/main/java/com/google/devtools/build/skydoc/BUILD
+++ b/src/main/java/com/google/devtools/build/skydoc/BUILD
@@ -84,7 +84,9 @@
"//src/main/java/com/google/devtools/build/skydoc/fakebuildapi/repository",
"//src/main/java/com/google/devtools/build/skydoc/fakebuildapi/test",
"//src/main/java/com/google/devtools/build/skydoc/rendering",
+ "//src/main/java/com/google/devtools/build/skydoc/rendering/proto:stardoc_output_java_proto",
"//src/main/java/com/google/devtools/common/options",
"//third_party:guava",
+ "//third_party:jsr305",
],
)
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 bb8a6ea..f794be5 100644
--- a/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
+++ b/src/main/java/com/google/devtools/build/skydoc/SkydocMain.java
@@ -102,11 +102,12 @@
import com.google.devtools.build.skydoc.fakebuildapi.test.FakeAnalysisTestResultInfoProvider;
import com.google.devtools.build.skydoc.fakebuildapi.test.FakeCoverageCommon;
import com.google.devtools.build.skydoc.fakebuildapi.test.FakeTestingModule;
+import com.google.devtools.build.skydoc.rendering.DocstringParseException;
+import com.google.devtools.build.skydoc.rendering.FunctionUtil;
import com.google.devtools.build.skydoc.rendering.MarkdownRenderer;
import com.google.devtools.build.skydoc.rendering.ProviderInfo;
import com.google.devtools.build.skydoc.rendering.RuleInfo;
-import com.google.devtools.build.skydoc.rendering.UserDefinedFunctionInfo;
-import com.google.devtools.build.skydoc.rendering.UserDefinedFunctionInfo.DocstringParseException;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.UserDefinedFunctionInfo;
import com.google.devtools.common.options.OptionsParser;
import java.io.IOException;
import java.io.PrintWriter;
@@ -287,7 +288,7 @@
for (Entry<String, UserDefinedFunction> entry : userDefinedFunctions.entrySet()) {
try {
UserDefinedFunctionInfo functionInfo =
- UserDefinedFunctionInfo.fromNameAndFunction(entry.getKey(), entry.getValue());
+ FunctionUtil.fromNameAndFunction(entry.getKey(), entry.getValue());
printUserDefinedFunctionInfo(printWriter, renderer, functionInfo);
printWriter.println();
} catch (DocstringParseException exception) {
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/DocstringParseException.java b/src/main/java/com/google/devtools/build/skydoc/rendering/DocstringParseException.java
new file mode 100644
index 0000000..a7825d1
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/DocstringParseException.java
@@ -0,0 +1,50 @@
+// Copyright 2019 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.devtools.build.skydoc.rendering;
+
+import com.google.devtools.build.lib.events.Location;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.UserDefinedFunctionInfo;
+import com.google.devtools.skylark.common.DocstringUtils.DocstringParseError;
+import java.util.List;
+
+/**
+ * An exception that may be thrown during construction of {@link UserDefinedFunctionInfo} if the
+ * function's docstring is malformed.
+ */
+public class DocstringParseException extends Exception {
+ public DocstringParseException(
+ String functionName, Location definedLocation, List<DocstringParseError> parseErrors) {
+ super(getMessage(functionName, definedLocation, parseErrors));
+ }
+
+ private static String getMessage(
+ String functionName, Location definedLocation, List<DocstringParseError> parseErrors) {
+ StringBuilder message = new StringBuilder();
+ message.append(
+ String.format(
+ "Unable to generate documentation for function %s (defined at %s) "
+ + "due to malformed docstring. Parse errors:\n",
+ functionName, definedLocation));
+ for (DocstringParseError parseError : parseErrors) {
+ message.append(
+ String.format(
+ " %s line %s: %s\n",
+ definedLocation,
+ parseError.getLineNumber(),
+ parseError.getMessage().replace('\n', ' ')));
+ }
+ return message.toString();
+ }
+}
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java b/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java
similarity index 70%
rename from src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java
rename to src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java
index 2e7c9df..2119b07 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionUtil.java
@@ -1,4 +1,4 @@
-// Copyright 2018 The Bazel Authors. All rights reserved.
+// Copyright 2019 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -17,7 +17,6 @@
import com.google.common.collect.ImmutableList;
import com.google.common.collect.Lists;
import com.google.common.collect.Maps;
-import com.google.devtools.build.lib.events.Location;
import com.google.devtools.build.lib.syntax.FunctionSignature;
import com.google.devtools.build.lib.syntax.Printer;
import com.google.devtools.build.lib.syntax.Printer.BasePrinter;
@@ -25,52 +24,17 @@
import com.google.devtools.build.lib.syntax.StringLiteral;
import com.google.devtools.build.lib.syntax.UserDefinedFunction;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.FunctionParamInfo;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.UserDefinedFunctionInfo;
import com.google.devtools.skylark.common.DocstringUtils;
import com.google.devtools.skylark.common.DocstringUtils.DocstringInfo;
import com.google.devtools.skylark.common.DocstringUtils.DocstringParseError;
import com.google.devtools.skylark.common.DocstringUtils.ParameterDoc;
-import java.util.Collection;
import java.util.List;
import java.util.Map;
import javax.annotation.Nullable;
-/** Encapsulates information about a user-defined Starlark function. */
-public class UserDefinedFunctionInfo {
-
- private final String functionName;
- private final Collection<FunctionParamInfo> parameters;
- private final String docString;
-
- /**
- * An exception that may be thrown during construction of {@link UserDefinedFunctionInfo} if the
- * function's docstring is malformed.
- */
- public static class DocstringParseException extends Exception {
- public DocstringParseException(
- String functionName, Location definedLocation, List<DocstringParseError> parseErrors) {
- super(getMessage(functionName, definedLocation, parseErrors));
- }
-
- private static String getMessage(
- String functionName, Location definedLocation, List<DocstringParseError> parseErrors) {
- StringBuilder message = new StringBuilder();
- message.append(
- String.format(
- "Unable to generate documentation for function %s (defined at %s) "
- + "due to malformed docstring. Parse errors:\n",
- functionName, definedLocation));
- for (DocstringParseError parseError : parseErrors) {
- message.append(
- String.format(
- " %s line %s: %s\n",
- definedLocation,
- parseError.getLineNumber(),
- parseError.getMessage().replace('\n', ' ')));
- }
- return message.toString();
- }
- }
-
+/** Contains a number of utility methods for functions and parameters. */
+public final class FunctionUtil {
/**
* Create and return a {@link UserDefinedFunctionInfo} object encapsulating information obtained
* from the given function and from its parsed docstring.
@@ -79,7 +43,8 @@
* the original exported function name; the function may have been renamed in the target
* Starlark file's scope)
* @param userDefinedFunction the raw function object
- * @throws DocstringParseException if the function's docstring is malformed
+ * @throws com.google.devtools.build.skydoc.rendering.DocstringParseException if the function's
+ * docstring is malformed
*/
public static UserDefinedFunctionInfo fromNameAndFunction(
String functionName, UserDefinedFunction userDefinedFunction) throws DocstringParseException {
@@ -105,11 +70,12 @@
paramNameToDocMap.put(paramDoc.getParameterName(), paramDoc.getDescription());
}
}
-
- return new UserDefinedFunctionInfo(
- functionName,
- parameterInfos(userDefinedFunction, paramNameToDocMap),
- functionDescription);
+ List<FunctionParamInfo> paramsInfo = parameterInfos(userDefinedFunction, paramNameToDocMap);
+ return UserDefinedFunctionInfo.newBuilder()
+ .setFunctionName(functionName)
+ .setDocString(functionDescription)
+ .addAllParameters(paramsInfo)
+ .build();
}
/** Constructor to be used for normal parameters. */
@@ -142,8 +108,7 @@
}
private static List<FunctionParamInfo> parameterInfos(
- UserDefinedFunction userDefinedFunction,
- Map<String, String> paramNameToDocMap) {
+ UserDefinedFunction userDefinedFunction, Map<String, String> paramNameToDocMap) {
FunctionSignature.WithValues<Object, SkylarkType> signature =
userDefinedFunction.getSignature();
ImmutableList.Builder<FunctionParamInfo> parameterInfos = ImmutableList.builder();
@@ -203,32 +168,4 @@
}
return parameterInfos.build();
}
-
- private UserDefinedFunctionInfo(
- String functionName, Collection<FunctionParamInfo> parameters, String docString) {
- this.functionName = functionName;
- this.parameters = parameters;
- this.docString = docString;
- }
-
- /** Returns the raw name of this function, for example, "my_function". */
- public String getName() {
- return functionName;
- }
-
- /**
- * Returns a collection of {@link FunctionParamInfo} objects, where each encapsulates information
- * about what of the function parameters. Ordering matches the actual Starlark function signature.
- */
- public Collection<FunctionParamInfo> getParameters() {
- return parameters;
- }
-
- /**
- * Returns the portion of the docstring that is not part of any special sections, such as "Args:"
- * or "Returns:". Returns the empty string if there is no docstring literal for this function.
- */
- public String getDocString() {
- return docString;
- }
}
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java
index 5591fe9..96dc91c 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownRenderer.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.skydoc.rendering;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.UserDefinedFunctionInfo;
import java.io.IOException;
import java.io.StringWriter;
import org.apache.velocity.VelocityContext;
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
index f902e01..3e9010f 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/MarkdownUtil.java
@@ -18,6 +18,7 @@
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeInfo;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeType;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.FunctionParamInfo;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.UserDefinedFunctionInfo;
import java.util.List;
import java.util.stream.Collectors;
@@ -62,10 +63,11 @@
*/
@SuppressWarnings("unused") // Used by markdown template.
public String funcSummary(UserDefinedFunctionInfo funcInfo) {
- List<String> paramNames = funcInfo.getParameters().stream()
- .map(param -> param.getName())
- .collect(Collectors.toList());
- return summary(funcInfo.getName(), paramNames);
+ List<String> paramNames =
+ funcInfo.getParametersList().stream()
+ .map(param -> param.getName())
+ .collect(Collectors.toList());
+ return summary(funcInfo.getFunctionName(), paramNames);
}
private String summary(String functionName, List<String> paramNames) {
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto b/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
index fc7feba..65b9061 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
@@ -65,6 +65,19 @@
bool mandatory = 4;
}
+// Representation of Starlark function definition.
+message UserDefinedFunctionInfo {
+ // The name of the function.
+ string function_name = 1;
+
+ // The parameters for the function.
+ repeated FunctionParamInfo parameters = 2;
+
+ // The documented description of the function (if specified in the function's
+ // docstring).
+ string doc_string = 3;
+}
+
// Representation of a Starlark function parameter definition.
message FunctionParamInfo {
// The name of the parameter.
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/templates/func.vm b/src/main/java/com/google/devtools/build/skydoc/rendering/templates/func.vm
index 3046495..a6bd36e 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/templates/func.vm
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/templates/func.vm
@@ -1,6 +1,6 @@
-<a name="#${funcInfo.name}"></a>
+<a name="#${funcInfo.functionName}"></a>
-#[[##]]# ${funcInfo.name}
+#[[##]]# ${funcInfo.functionName}
<pre>
${util.funcSummary($funcInfo)}
@@ -8,7 +8,7 @@
${funcInfo.docString}
-#if (!$funcInfo.parameters.isEmpty())
+#if (!$funcInfo.getParametersList().isEmpty())
#[[###]]# Parameters
<table class="params-table">
@@ -17,8 +17,8 @@
<col class="col-description" />
</colgroup>
<tbody>
-#foreach ($param in $funcInfo.parameters)
- <tr id="${funcInfo.name}-${param.name}">
+#foreach ($param in $funcInfo.getParametersList())
+ <tr id="${funcInfo.functionName}-${param.name}">
<td><code>${param.name}</code></td>
<td>
${util.mandatoryString($param)}.#if(!$param.getDefaultValue().isEmpty()) default is <code>$param.getDefaultValue()</code>#end
diff --git a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
index 0601cf6..0948690 100644
--- a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
+++ b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
@@ -28,9 +28,9 @@
import com.google.devtools.build.lib.vfs.FileSystemUtils;
import com.google.devtools.build.lib.vfs.Path;
import com.google.devtools.build.skydoc.SkydocMain.StarlarkEvaluationException;
+import com.google.devtools.build.skydoc.rendering.DocstringParseException;
+import com.google.devtools.build.skydoc.rendering.FunctionUtil;
import com.google.devtools.build.skydoc.rendering.RuleInfo;
-import com.google.devtools.build.skydoc.rendering.UserDefinedFunctionInfo;
-import com.google.devtools.build.skydoc.rendering.UserDefinedFunctionInfo.DocstringParseException;
import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeType;
import java.io.IOException;
import java.util.Map;
@@ -377,7 +377,7 @@
DocstringParseException expected =
assertThrows(
DocstringParseException.class,
- () -> UserDefinedFunctionInfo.fromNameAndFunction("check_sources", checkSourcesFn));
+ () -> FunctionUtil.fromNameAndFunction("check_sources", checkSourcesFn));
assertThat(expected)
.hasMessageThat()
.contains(
