Refactor FunctionParamInfo into a proto. PiperOrigin-RevId: 251708686
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionParamInfo.java b/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionParamInfo.java deleted file mode 100644 index 81dafe9..0000000 --- a/src/main/java/com/google/devtools/build/skydoc/rendering/FunctionParamInfo.java +++ /dev/null
@@ -1,93 +0,0 @@ -// Copyright 2018 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.syntax.Printer; -import com.google.devtools.build.lib.syntax.Printer.BasePrinter; -import javax.annotation.Nullable; - -/** Stores information about a function parameter definition. */ -public class FunctionParamInfo { - - private final String name; - private final String docString; - @Nullable private final Object defaultValue; - private final boolean mandatory; - - private FunctionParamInfo( - String name, String docString, @Nullable Object defaultValue, boolean mandatory) { - this.name = name; - this.docString = docString; - this.defaultValue = defaultValue; - this.mandatory = mandatory; - } - - /** Constructor to be used for normal parameters. */ - public static FunctionParamInfo forParam( - String name, String docString, @Nullable Object defaultValue) { - return new FunctionParamInfo(name, docString, defaultValue, defaultValue == null); - } - - /** Constructor to be used for *args or **kwargs. */ - public static FunctionParamInfo forSpecialParam(String name, String docString) { - return new FunctionParamInfo(name, docString, null, false); - } - - /** - * Return the name of this parameter (for example, in 'def foo(bar):', the only parameter is - * named 'bar'. - */ - public String getName() { - return name; - } - - /** - * Return the documented description of this parameter (if specified in the function's docstring). - */ - public String getDocString() { - return docString; - } - - /** - * Returns true if this function has a default value and the default value can be displayed - * as a string. - */ - public boolean hasDefaultValueString() { - return defaultValue != null && !getDefaultString().isEmpty(); - } - - /** - * Returns a string representing the default value this function parameter. - * - * @throws IllegalStateException if there is no default value of this function parameter; - * invoke {@link #hasDefaultValueString()} first to check whether there is a default - * parameter - */ - public String getDefaultString() { - if (defaultValue == null) { - return ""; - } - BasePrinter printer = Printer.getSimplifiedPrinter(); - printer.repr(defaultValue); - return printer.toString(); - } - - /** - * Returns 'required' if this parameter is mandatory, otherwise returns 'optional'. - */ - public String getMandatoryString() { - return mandatory ? "required" : "optional"; - } -}
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 ff13751..f902e01 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
@@ -17,6 +17,7 @@ import com.google.common.base.Joiner; 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 java.util.List; import java.util.stream.Collectors; @@ -112,6 +113,14 @@ return attrInfo.getMandatory() ? "required" : "optional"; } + /** + * Returns "required" if providing a value for this parameter is mandatory. Otherwise, returns + * "optional". + */ + public String mandatoryString(FunctionParamInfo paramInfo) { + return paramInfo.getMandatory() ? "required" : "optional"; + } + private String attributeTypeDescription(AttributeType attributeType) { switch (attributeType) { case NAME:
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java b/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java index afe3f3e..2e7c9df 100644 --- a/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java +++ b/src/main/java/com/google/devtools/build/skydoc/rendering/UserDefinedFunctionInfo.java
@@ -19,9 +19,12 @@ 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; import com.google.devtools.build.lib.syntax.SkylarkType; 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.skylark.common.DocstringUtils; import com.google.devtools.skylark.common.DocstringUtils.DocstringInfo; import com.google.devtools.skylark.common.DocstringUtils.DocstringParseError; @@ -29,6 +32,7 @@ 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 { @@ -108,6 +112,35 @@ functionDescription); } + /** Constructor to be used for normal parameters. */ + public static FunctionParamInfo forParam( + String name, String docString, @Nullable Object defaultValue) { + FunctionParamInfo.Builder paramBuilder = + FunctionParamInfo.newBuilder().setName(name).setDocString(docString); + if (defaultValue == null) { + paramBuilder.setMandatory(true); + } else { + BasePrinter printer = Printer.getSimplifiedPrinter(); + printer.repr(defaultValue); + String defaultValueString = printer.toString(); + + if (defaultValueString.isEmpty()) { + defaultValueString = "{unknown object}"; + } + paramBuilder.setDefaultValue(defaultValueString).setMandatory(false); + } + return paramBuilder.build(); + } + + /** Constructor to be used for *args or **kwargs. */ + public static FunctionParamInfo forSpecialParam(String name, String docString) { + return FunctionParamInfo.newBuilder() + .setName(name) + .setDocString(docString) + .setMandatory(false) + .build(); + } + private static List<FunctionParamInfo> parameterInfos( UserDefinedFunction userDefinedFunction, Map<String, String> paramNameToDocMap) { @@ -126,7 +159,7 @@ for (paramIndex = 0; paramIndex < numMandatoryParams; paramIndex++) { String paramName = paramNames.get(paramIndex); String paramDoc = paramNameToDocMap.getOrDefault(paramName, ""); - parameterInfos.add(FunctionParamInfo.forParam(paramName, paramDoc, /*default param*/ null)); + parameterInfos.add(forParam(paramName, paramDoc, /*default param*/ null)); } // Parameters with defaults. @@ -138,7 +171,7 @@ if (paramNameToDocMap.containsKey(paramName)) { paramDoc = paramNameToDocMap.get(paramName); } - parameterInfos.add(FunctionParamInfo.forParam(paramName, paramDoc, defaultParamValue)); + parameterInfos.add(forParam(paramName, paramDoc, defaultParamValue)); paramIndex++; } } @@ -152,7 +185,7 @@ } else if (paramNameToDocMap.containsKey("*" + paramName)) { paramDoc = paramNameToDocMap.get("*" + paramName); } - parameterInfos.add(FunctionParamInfo.forSpecialParam(paramName, paramDoc)); + parameterInfos.add(forSpecialParam(paramName, paramDoc)); paramIndex++; } @@ -165,7 +198,7 @@ } else if (paramNameToDocMap.containsKey("**" + paramName)) { paramDoc = paramNameToDocMap.get("**" + paramName); } - parameterInfos.add(FunctionParamInfo.forSpecialParam(paramName, paramDoc)); + parameterInfos.add(forSpecialParam(paramName, paramDoc)); paramIndex++; } return parameterInfos.build();
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 004d3b9..4b35a1e 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
@@ -64,3 +64,22 @@ // If true, all targets of the rule must specify a value for this attribute. bool mandatory = 4; } + +// Representation of a Starlark function parameter definition. +message FunctionParamInfo { + // The name of the parameter. + string name = 1; + + // The documented description of the parameter (if specified in the function's + // docstring). + string doc_string = 2; + + // If not an empty string, the default value of the parameter displayed + // as a string. + string default_value = 3; + + // If true, the default value is unset and a value is needed for this + // parameter. This might be false even if defaultValue is empty in the case of + // special parameter such as *args and **kwargs" + bool mandatory = 4; +}
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 17ac789..3046495 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
@@ -21,11 +21,11 @@ <tr id="${funcInfo.name}-${param.name}"> <td><code>${param.name}</code></td> <td> - ${param.mandatoryString}.#if($param.hasDefaultValueString()) default is <code>${param.defaultString}</code>#end + ${util.mandatoryString($param)}.#if(!$param.getDefaultValue().isEmpty()) default is <code>$param.getDefaultValue()</code>#end #if (!$param.docString.isEmpty()) <p> - ${param.docString} + ${param.docString.trim()} </p> #end </td>