diff options
Diffstat (limited to 'src/main/java/com/google/devtools')
4 files changed, 13 insertions, 5 deletions
diff --git a/src/main/java/com/google/devtools/build/docgen/RuleDocumentation.java b/src/main/java/com/google/devtools/build/docgen/RuleDocumentation.java index e8835f4c29..51fe1180a3 100644 --- a/src/main/java/com/google/devtools/build/docgen/RuleDocumentation.java +++ b/src/main/java/com/google/devtools/build/docgen/RuleDocumentation.java @@ -203,7 +203,7 @@ class RuleDocumentation implements Comparable<RuleDocumentation> { sb.append(String.format("<li id=\"%s.%s\"%s><code>%s</code>:\n%s</li>\n", ruleName.toLowerCase(), attrName, getDeprecatedString( attributeDoc.hasFlag(DocgenConsts.FLAG_DEPRECATED)), - attrName, attributeDoc.getHtmlDocumentation(attribute))); + attrName, attributeDoc.getHtmlDocumentation(attribute, ruleName))); } } sb.append("</ul>\n"); diff --git a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java index 0bdc1f1f3f..769c010967 100644 --- a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java +++ b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java @@ -40,12 +40,14 @@ class RuleDocumentationAttribute implements Comparable<RuleDocumentationAttribut private static final Map<Type<?>, String> TYPE_DESC = ImmutableMap.<Type<?>, String>builder() .put(Type.BOOLEAN, "Boolean") .put(Type.INTEGER, "Integer") - .put(Type.INTEGER_LIST, "List of Integer") + .put(Type.INTEGER_LIST, "List of integers") .put(Type.STRING, "String") - .put(Type.STRING_LIST, "List of String") + .put(Type.STRING_LIST, "List of strings") .put(Type.TRISTATE, "Integer") .put(Type.LABEL, "<a href=\"build-ref.html#labels\">Label</a>") .put(Type.LABEL_LIST, "List of <a href=\"build-ref.html#labels\">labels</a>") + .put(Type.LABEL_LIST_DICT, + "Dictionary mapping strings to lists of <a href=\"build-ref.html#labels\">labels</a>") .put(Type.NODEP_LABEL, "<a href=\"build-ref.html#name\">Name</a>") .put(Type.NODEP_LABEL_LIST, "List of <a href=\"build-ref.html#name\">names</a>") .put(Type.OUTPUT, "<a href=\"build-ref.html#filename\">Filename</a>") @@ -102,7 +104,7 @@ class RuleDocumentationAttribute implements Comparable<RuleDocumentationAttribut /** * Returns the raw html documentation of the rule attribute. */ - String getHtmlDocumentation(Attribute attribute) { + String getHtmlDocumentation(Attribute attribute, String ruleName) { // TODO(bazel-team): this is needed for common type attributes. Fix those and remove this. if (attribute == null) { return htmlDocumentation; @@ -113,7 +115,11 @@ class RuleDocumentationAttribute implements Comparable<RuleDocumentationAttribut .append("; " + (attribute.isMandatory() ? "required" : "optional")) .append(getDefaultValue(attribute)) .append(")</i><br/>\n"); - return htmlDocumentation.replace("${" + DocgenConsts.VAR_SYNOPSIS + "}", sb.toString()); + String synposisVar = "${" + DocgenConsts.VAR_SYNOPSIS + "}"; + if (!flags.contains(DocgenConsts.FLAG_DEPRECATED) && !htmlDocumentation.contains(synposisVar)) { + System.err.println("WARNING: No synopsis found for " + ruleName + "." + attributeName); + } + return htmlDocumentation.replace(synposisVar, sb.toString()); } private String getDefaultValue(Attribute attribute) { diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/ConfigRuleClasses.java b/src/main/java/com/google/devtools/build/lib/analysis/config/ConfigRuleClasses.java index 438f6234b4..dd0ba5b5d9 100644 --- a/src/main/java/com/google/devtools/build/lib/analysis/config/ConfigRuleClasses.java +++ b/src/main/java/com/google/devtools/build/lib/analysis/config/ConfigRuleClasses.java @@ -100,6 +100,7 @@ public class ConfigRuleClasses { return builder /* <!-- #BLAZE_RULE(config_setting).ATTRIBUTE(values) --> The set of configuration values that match this rule (expressed as Blaze flags) + ${SYNOPSIS} <i>(Dictionary mapping flags to expected values, both expressed as strings; mandatory)</i> diff --git a/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java b/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java index c3f2dd2a35..bfdb632328 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java +++ b/src/main/java/com/google/devtools/build/lib/rules/workspace/BindRule.java @@ -38,6 +38,7 @@ public final class BindRule implements RuleDefinition { return builder /* <!-- #BLAZE_RULE(bind).ATTRIBUTE(actual) --> The target to be aliased. + ${SYNOPSIS} <p>This target must exist, but can be any type of rule (including bind).</p> <!-- #END_BLAZE_RULE.ATTRIBUTE --> */ |