Refactor AttributeInfo into a proto
This is a no-op in functionality, but begins to pave the way for a proto output format for Stardoc.
RELNOTES: None.
PiperOrigin-RevId: 244020123
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/AttributeInfo.java b/src/main/java/com/google/devtools/build/skydoc/rendering/AttributeInfo.java
deleted file mode 100644
index 0361932..0000000
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/AttributeInfo.java
+++ /dev/null
@@ -1,89 +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;
-
-/**
- * Stores information about a skylark attribute definition.
- */
-public class AttributeInfo {
-
- private final String name;
- private final String docString;
- private final Type type;
- private final boolean mandatory;
-
- public AttributeInfo(String name, String docString, Type type, boolean mandatory) {
- this.name = name;
- this.docString = docString.trim();
- this.type = type;
- this.mandatory = mandatory;
- }
-
- @SuppressWarnings("unused") // Used by markdown template.
- public String getName() {
- return name;
- }
-
- @SuppressWarnings("unused") // Used by markdown template.
- public String getDocString() {
- return docString;
- }
-
- @SuppressWarnings("unused") // Used by markdown template.
- public Type getType() {
- return type;
- }
-
- /**
- * Returns a string representing whether this attribute is required or optional.
- */
- @SuppressWarnings("unused") // Used by markdown template.
- public String getMandatoryString() {
- return mandatory ? "required" : "optional";
- }
-
- /**
- * Attribute type. For example, an attribute described by attr.label() will be of type LABEL.
- */
- public enum Type {
- NAME("Name"),
- INT("Integer"),
- LABEL("Label"),
- STRING("String"),
- STRING_LIST("List of strings"),
- INT_LIST("List of integers"),
- LABEL_LIST("List of labels"),
- BOOLEAN("Boolean"),
- LICENSE("List of strings"),
- LABEL_STRING_DICT("Dictionary: Label -> String"),
- STRING_DICT("Dictionary: String -> String"),
- STRING_LIST_DICT("Dictionary: String -> List of strings"),
- OUTPUT("Label"),
- OUTPUT_LIST("List of labels");
-
- private final String description;
-
- Type(String description) {
- this.description = description;
- }
-
- /**
- * Returns a human-readable string representing this attribute type.
- */
- public String getDescription() {
- return description;
- }
- }
-}
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/BUILD b/src/main/java/com/google/devtools/build/skydoc/rendering/BUILD
index d3603e2..1cf5d90 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/BUILD
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/BUILD
@@ -17,6 +17,7 @@
"//src/main/java/com/google/devtools/build/lib:events",
"//src/main/java/com/google/devtools/build/lib:skylarkinterface",
"//src/main/java/com/google/devtools/build/lib:syntax",
+ "//src/main/java/com/google/devtools/build/skydoc/rendering/proto:stardoc_output_java_proto",
"//src/tools/skylark/java/com/google/devtools/skylark/common",
"//third_party:apache_velocity",
"//third_party:guava",
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 335bda8..ff13751 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
@@ -15,6 +15,8 @@
package com.google.devtools.build.skydoc.rendering;
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 java.util.List;
import java.util.stream.Collectors;
@@ -99,9 +101,49 @@
break;
}
if (typeLink == null) {
- return attrInfo.getType().getDescription();
+ return attributeTypeDescription(attrInfo.getType());
} else {
- return String.format("<a href=\"%s\">%s</a>", typeLink, attrInfo.getType().getDescription());
+ return String.format(
+ "<a href=\"%s\">%s</a>", typeLink, attributeTypeDescription(attrInfo.getType()));
}
}
+
+ public String mandatoryString(AttributeInfo attrInfo) {
+ return attrInfo.getMandatory() ? "required" : "optional";
+ }
+
+ private String attributeTypeDescription(AttributeType attributeType) {
+ switch (attributeType) {
+ case NAME:
+ return "Name";
+ case INT:
+ return "Integer";
+ case LABEL:
+ return "Label";
+ case STRING:
+ return "String";
+ case STRING_LIST:
+ return "List of strings";
+ case INT_LIST:
+ return "List of integers";
+ case LABEL_LIST:
+ return "List of labels";
+ case BOOLEAN:
+ return "Boolean";
+ case LABEL_STRING_DICT:
+ return "Dictionary: Label -> String";
+ case STRING_DICT:
+ return "Dictionary: String -> String";
+ case STRING_LIST_DICT:
+ return "Dictionary: String -> List of strings";
+ case OUTPUT:
+ return "Label";
+ case OUTPUT_LIST:
+ return "List of labels";
+ case UNKNOWN:
+ case UNRECOGNIZED:
+ throw new IllegalArgumentException("Unhandled type " + attributeType);
+ }
+ throw new IllegalArgumentException("Unhandled type " + attributeType);
+ }
}
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/RuleInfo.java b/src/main/java/com/google/devtools/build/skydoc/rendering/RuleInfo.java
index 6f231cf..b1c795a 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/RuleInfo.java
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/RuleInfo.java
@@ -16,6 +16,7 @@
import com.google.devtools.build.lib.events.Location;
import com.google.devtools.build.lib.syntax.BaseFunction;
+import com.google.devtools.build.skydoc.rendering.proto.StardocOutputProtos.AttributeInfo;
import java.util.Collection;
/**
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/proto/BUILD b/src/main/java/com/google/devtools/build/skydoc/rendering/proto/BUILD
new file mode 100644
index 0000000..510022e
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/proto/BUILD
@@ -0,0 +1,31 @@
+package(
+ default_visibility = [
+ "//src/main/java/com/google/devtools/build/skydoc:__subpackages__",
+ "//src/test/java/com/google/devtools/build/skydoc:__subpackages__",
+ ],
+)
+
+load("//tools/build_rules:utilities.bzl", "java_library_srcs")
+
+licenses(["notice"]) # Apache 2.0
+
+filegroup(
+ name = "srcs",
+ srcs = glob(["**"]),
+)
+
+proto_library(
+ name = "stardoc_output_proto",
+ srcs = ["stardoc_output.proto"],
+)
+
+java_proto_library(
+ name = "stardoc_output_java_proto",
+ deps = [":stardoc_output_proto"],
+)
+
+java_library_srcs(
+ name = "dist_jars",
+ visibility = ["//src:__pkg__"],
+ deps = [":stardoc_output_java_proto"],
+)
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
new file mode 100644
index 0000000..004d3b9
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/proto/stardoc_output.proto
@@ -0,0 +1,66 @@
+// 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.
+//
+// Protos for Stardoc data.
+//
+// Stardoc collects information about Starlark functions, providers, and rules.
+syntax = "proto3";
+
+package stardoc_output;
+
+// option java_api_version = 2;
+option java_package = "com.google.devtools.build.skydoc.rendering.proto";
+option java_outer_classname = "StardocOutputProtos";
+
+// Representation of a Starlark rule attribute type. These generally
+// have a one-to-one correspondence with functions defined at
+// https://docs.bazel.build/versions/master/skylark/lib/attr.html.
+enum AttributeType {
+ UNKNOWN = 0;
+ // A special case of STRING; all rules have exactly one implicit
+ // attribute "name" of type NAME.
+ NAME = 1;
+ INT = 2;
+ LABEL = 3;
+ STRING = 4;
+ STRING_LIST = 5;
+ INT_LIST = 6;
+ LABEL_LIST = 7;
+ BOOLEAN = 8;
+ LABEL_STRING_DICT = 9;
+ STRING_DICT = 10;
+ STRING_LIST_DICT = 11;
+ OUTPUT = 12;
+ OUTPUT_LIST = 13;
+}
+
+// Representation of a Starlark rule attribute definition, comprised of an
+// attribute name, and a schema defined by a call to one of the 'attr' module
+// methods enumerated at
+// https://docs.bazel.build/versions/master/skylark/lib/attr.html
+message AttributeInfo {
+ // The name of the attribute.
+ string name = 1;
+
+ // The documentation string of the attribute, supplied via the 'doc'
+ // parameter to the schema-creation call.
+ string doc_string = 2;
+
+ // The type of the attribute, defined generally by which function is invoked
+ // in the attr module.
+ AttributeType type = 3;
+
+ // If true, all targets of the rule must specify a value for this attribute.
+ bool mandatory = 4;
+}
diff --git a/src/main/java/com/google/devtools/build/skydoc/rendering/templates/rule.vm b/src/main/java/com/google/devtools/build/skydoc/rendering/templates/rule.vm
index 209c324..d9ea3bf 100644
--- a/src/main/java/com/google/devtools/build/skydoc/rendering/templates/rule.vm
+++ b/src/main/java/com/google/devtools/build/skydoc/rendering/templates/rule.vm
@@ -21,10 +21,10 @@
<tr id="${ruleName}-${attribute.name}">
<td><code>${attribute.name}</code></td>
<td>
- ${util.attributeTypeString($attribute)}; ${attribute.mandatoryString}
+ ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)}
#if (!$attribute.docString.isEmpty())
<p>
- ${attribute.docString}
+ ${attribute.docString.trim()}
</p>
#end
</td>
