Make the BE docgen's code a bit nicer.
Remove unused section (Generating rules) and simplify the code that
reads basic rule definitions (name, type, family) in for example:
<!-- #BLAZE_RULE (NAME = cc_binary, TYPE = BINARY, FAMILY = C / C++) -->
--
MOS_MIGRATED_REVID=88200584
diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
index 8a1a02d..baf3399 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
@@ -188,30 +188,31 @@
Set<RuleDocumentation> binaryDocs = new TreeSet<>();
Set<RuleDocumentation> libraryDocs = new TreeSet<>();
Set<RuleDocumentation> testDocs = new TreeSet<>();
- Set<RuleDocumentation> generateDocs = new TreeSet<>();
Set<RuleDocumentation> otherDocs = new TreeSet<>();
for (RuleDocumentation doc : docEntries) {
RuleClass ruleClass = ruleClassProvider.getRuleClassMap().get(doc.getRuleName());
- if (ruleClass.isDocumented()) {
- if (doc.isLanguageSpecific()) {
- switch(doc.getRuleType()) {
- case BINARY:
- binaryDocs.add(doc);
- break;
- case LIBRARY:
- libraryDocs.add(doc);
- break;
- case TEST:
- testDocs.add(doc);
- break;
- case OTHER:
- otherDocs.add(doc);
- break;
- }
- } else {
- otherDocs.add(doc);
+ if (!ruleClass.isDocumented()) {
+ continue;
+ }
+
+ if (doc.isLanguageSpecific()) {
+ switch(doc.getRuleType()) {
+ case BINARY:
+ binaryDocs.add(doc);
+ break;
+ case LIBRARY:
+ libraryDocs.add(doc);
+ break;
+ case TEST:
+ testDocs.add(doc);
+ break;
+ case OTHER:
+ otherDocs.add(doc);
+ break;
}
+ } else {
+ otherDocs.add(doc);
}
}
@@ -223,7 +224,6 @@
DocgenConsts.VAR_SECTION_BINARY, getRuleDocs(binaryDocs),
DocgenConsts.VAR_SECTION_LIBRARY, getRuleDocs(libraryDocs),
DocgenConsts.VAR_SECTION_TEST, getRuleDocs(testDocs),
- DocgenConsts.VAR_SECTION_GENERATE, getRuleDocs(generateDocs),
DocgenConsts.VAR_SECTION_OTHER, getRuleDocs(otherDocs));
bw.write("\n"); // for the benefit of the block-beginning comment at the top of the template
bw.write(SourceFileReader.readTemplateContents(DocgenConsts.BODY_TEMPLATE, sectionMapping));
diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index e1edf29..01bf7d6 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -39,7 +39,6 @@
public static final String VAR_SECTION_BINARY = "SECTION_BINARY";
public static final String VAR_SECTION_LIBRARY = "SECTION_LIBRARY";
public static final String VAR_SECTION_TEST = "SECTION_TEST";
- public static final String VAR_SECTION_GENERATE = "SECTION_GENERATE";
public static final String VAR_SECTION_OTHER = "SECTION_OTHER";
public static final String VAR_IMPLICIT_OUTPUTS = "IMPLICIT_OUTPUTS";
@@ -133,6 +132,7 @@
public static final Pattern BLAZE_RULE_ATTR_END = Pattern.compile(
"^[\\s]*\\<!\\-\\-[\\s]*#END_BLAZE_RULE\\.ATTRIBUTE[\\s]*\\-\\-\\>[\\s]*\\*/");
+ /** e.g. "[DEPRECATED]" in <!-- #BLAZE_RULE(...).ATTRIBUTE(...)[DEPRECATED] --> */
public static final Pattern BLAZE_RULE_FLAGS = Pattern.compile("^.*\\[(.*)\\].*$");
public static final Map<String, Integer> ATTRIBUTE_ORDERING = ImmutableMap
diff --git a/src/main/java/com/google/devtools/build/docgen/SourceFileReader.java b/src/main/java/com/google/devtools/build/docgen/SourceFileReader.java
index c17b3f6..f3a42f3 100644
--- a/src/main/java/com/google/devtools/build/docgen/SourceFileReader.java
+++ b/src/main/java/com/google/devtools/build/docgen/SourceFileReader.java
@@ -13,6 +13,7 @@
// limitations under the License.
package com.google.devtools.build.docgen;
+import com.google.common.base.Splitter;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.LinkedListMultimap;
import com.google.common.collect.ListMultimap;
@@ -141,12 +142,30 @@
private void startBlazeRuleDoc(String line, Matcher matcher)
throws BuildEncyclopediaDocException {
checkDocValidity();
- // Start of a new rule
- String[] metaData = matcher.group(1).split(",");
+ // Start of a new rule.
+ // e.g.: matcher.group(1) = "NAME = cc_binary, TYPE = BINARY, FAMILY = C / C++"
+ for (String group : Splitter.on(",").split(matcher.group(1))) {
+ List<String> parts = Splitter.on("=").limit(2).splitToList(group);
+ boolean good = false;
+ if (parts.size() == 2) {
+ String key = parts.get(0).trim();
+ String value = parts.get(1).trim();
+ good = true;
+ if (DocgenConsts.META_KEY_NAME.equals(key)) {
+ ruleName = value;
+ } else if (DocgenConsts.META_KEY_TYPE.equals(key)) {
+ ruleType = value;
+ } else if (DocgenConsts.META_KEY_FAMILY.equals(key)) {
+ ruleFamily = value;
+ } else {
+ good = false;
+ }
+ }
+ if (!good) {
+ System.err.printf("WARNING: bad rule definition in line %d: '%s'", getLineCnt(), line);
+ }
+ }
- ruleName = readMetaData(metaData, DocgenConsts.META_KEY_NAME);
- ruleType = readMetaData(metaData, DocgenConsts.META_KEY_TYPE);
- ruleFamily = readMetaData(metaData, DocgenConsts.META_KEY_FAMILY);
startLineCnt = getLineCnt();
addFlags(line);
inBlazeRuleDocs = true;
@@ -224,11 +243,10 @@
docMap.get(docVariable.getRuleName()).addDocVariable(
docVariable.getVariableName(), docVariable.getValue());
} else {
- throw new BuildEncyclopediaDocException(javaSourceFilePath,
- docVariable.getStartLineCnt(), String.format(
- "Malformed rule variable #BLAZE_RULE(%s).%s, "
- + "rule %s not found in file.", docVariable.getRuleName(),
- docVariable.getVariableName(), docVariable.getRuleName()));
+ throw new BuildEncyclopediaDocException(javaSourceFilePath, docVariable.getStartLineCnt(),
+ String.format("Malformed rule variable #BLAZE_RULE(%s).%s, rule %s not found in file.",
+ docVariable.getRuleName(), docVariable.getVariableName(),
+ docVariable.getRuleName()));
}
}
ruleDocEntries = docMap.values();
@@ -243,20 +261,6 @@
return attributeDocEntries;
}
- private String readMetaData(String[] metaData, String metaKey) {
- for (String metaDataItem : metaData) {
- String[] metaDataItemParts = metaDataItem.split("=", 2);
- if (metaDataItemParts.length != 2) {
- return null;
- }
-
- if (metaDataItemParts[0].trim().equals(metaKey)) {
- return metaDataItemParts[1].trim();
- }
- }
- return null;
- }
-
/**
* Reads the template file without variable substitution.
*/
@@ -266,28 +270,30 @@
}
/**
- * Reads the template file and expands the variables. The variables has to have
- * the following format in the template file: ${VARIABLE_NAME}. In the Map
- * input parameter the key has to be VARIABLE_NAME. Variables can be null.
+ * Reads a template file and substitutes variables of the format ${FOO}.
+ *
+ * @param variables keys are the possible variable names, e.g. "FOO", values are the substitutions
+ * (can be null)
*/
- public static String readTemplateContents(
- String templateFilePath, final Map<String, String> variables)
- throws BuildEncyclopediaDocException, IOException {
+ public static String readTemplateContents(String templateFilePath,
+ final Map<String, String> variables) throws BuildEncyclopediaDocException, IOException {
final StringBuilder sb = new StringBuilder();
readTextFile(templateFilePath, new ReadAction() {
@Override
public void readLineImpl(String line) {
- sb.append(expandVariables(line, variables) + LS);
+ sb.append(expandVariables(line, variables)).append(LS);
}
});
return sb.toString();
}
private static String expandVariables(String line, Map<String, String> variables) {
- if (variables != null) {
- for (Entry<String, String> variable : variables.entrySet()) {
- line = line.replace("${" + variable.getKey() + "}", variable.getValue());
- }
+ if (variables == null || line.indexOf("${") == -1) {
+ return line;
+ }
+
+ for (Entry<String, String> variable : variables.entrySet()) {
+ line = line.replace("${" + variable.getKey() + "}", variable.getValue());
}
return line;
}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be-body.html b/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
index 29c6828..dabadb8 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be-body.html
@@ -34,14 +34,6 @@
${SECTION_TEST}
<!-- ============================================
- generate code and data
- ============================================
--->
-<h2>Rules to Generate Code and Data</h2>
-
-${SECTION_GENERATE}
-
-<!-- ============================================
variables
============================================
-->
