Change blacklist -> denylist in bazel docgen.
RELNOTES: None
PiperOrigin-RevId: 335031053
diff --git a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
index 0a792b4..02b1d8e 100644
--- a/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
+++ b/src/main/java/com/google/devtools/build/docgen/ApiExporter.java
@@ -279,7 +279,7 @@
private static void printUsage(OptionsParser parser) {
System.err.println(
"Usage: api_exporter_bin -n product_name -p rule_class_provider (-i input_dir)+\n"
- + " -f outputFile [-b blacklist] [-h]\n\n"
+ + " -f outputFile [-b denylist] [-h]\n\n"
+ "Exports all Starlark builtins to a file including the embedded native rules.\n"
+ "The product name (-n), rule class provider (-p), output file (-f) and at least \n"
+ " one input_dir (-i) must be specified.\n");
@@ -310,7 +310,7 @@
try {
SymbolFamilies symbols =
new SymbolFamilies(
- options.productName, options.provider, options.inputDirs, options.blacklist);
+ options.productName, options.provider, options.inputDirs, options.denylist);
Builtins.Builder builtins = Builtins.newBuilder();
appendTypes(builtins, symbols.getTypes(), symbols.getNativeRules());
diff --git a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
index 38f5f1b..552976c 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
@@ -56,18 +56,18 @@
}
/**
- * Parse the file containing blacklisted rules for documentation. The list is simply a list of
- * rules separated by new lines. Line comments can be added to the file by starting them with #.
+ * Parse the file containing rules blocked from documentation. The list is simply a list of rules
+ * separated by new lines. Line comments can be added to the file by starting them with #.
*
- * @param blackList The name of the file containing the blacklist.
- * @return The set of blacklisted rules.
+ * @param denyList The name of the file containing the denylist.
+ * @return The set of denylisted rules.
* @throws IOException
*/
@VisibleForTesting
- public static Set<String> readBlackList(String blackList) throws IOException {
+ public static Set<String> readDenyList(String denyList) throws IOException {
Set<String> result = new HashSet<String>();
- if (blackList != null && !blackList.isEmpty()) {
- File file = new File(blackList);
+ if (denyList != null && !denyList.isEmpty()) {
+ File file = new File(denyList);
try (BufferedReader reader = Files.newBufferedReader(file.toPath(), UTF_8)) {
for (String line = reader.readLine(); line != null; line = reader.readLine()) {
String rule = SHARP_SPLITTER.split(line).iterator().next();
@@ -84,27 +84,27 @@
* Creates a map of rule names (keys) to rule documentation (values).
*
* <p>This method crawls the specified input directories for rule class definitions (as Java
- * source files) which contain the rules' and attributes' definitions as comments in a
- * specific format. The keys in the returned Map correspond to these rule classes.
+ * source files) which contain the rules' and attributes' definitions as comments in a specific
+ * format. The keys in the returned Map correspond to these rule classes.
*
* <p>In the Map's values, all references pointing to other rules, rule attributes, and general
- * documentation (e.g. common definitions, make variables, etc.) are expanded into hyperlinks.
- * The links generated follow either the multi-page or single-page Build Encyclopedia model
- * depending on the mode set for the provided {@link RuleLinkExpander}.
+ * documentation (e.g. common definitions, make variables, etc.) are expanded into hyperlinks. The
+ * links generated follow either the multi-page or single-page Build Encyclopedia model depending
+ * on the mode set for the provided {@link RuleLinkExpander}.
*
* @param inputDirs list of directories to scan for documentation
- * @param blackList specify an optional blacklist file that list some rules that should
- * not be listed in the output.
+ * @param denyList specify an optional denylist file that list some rules that should not be
+ * listed in the output.
* @param expander The RuleLinkExpander, which is used for expanding links in the rule doc.
* @throws BuildEncyclopediaDocException
* @throws IOException
* @return Map of rule class to rule documentation.
*/
public Map<String, RuleDocumentation> collect(
- List<String> inputDirs, String blackList, RuleLinkExpander expander)
+ List<String> inputDirs, String denyList, RuleLinkExpander expander)
throws BuildEncyclopediaDocException, IOException {
- // Read the blackList file
- Set<String> blacklistedRules = readBlackList(blackList);
+ // Read the denyList file
+ Set<String> denylistedRules = readDenyList(denyList);
// RuleDocumentations are generated in order (based on rule type then alphabetically).
// The ordering is also used to determine in which rule doc the common attribute docs are
// generated (they are generated at the first appearance).
@@ -127,8 +127,13 @@
System.out.println(" Processing input directory: " + inputDir);
}
int ruleNum = ruleDocEntries.size();
- collectDocs(processedFiles, ruleClassFiles, ruleDocEntries, blacklistedRules,
- attributeDocEntries, new File(inputDir));
+ collectDocs(
+ processedFiles,
+ ruleClassFiles,
+ ruleDocEntries,
+ denylistedRules,
+ attributeDocEntries,
+ new File(inputDir));
if (printMessages) {
System.out.println(" " + (ruleDocEntries.size() - ruleNum)
+ " rule documentations found.");
@@ -155,16 +160,16 @@
* links generated follow the multi-page Build Encyclopedia model (one page per rule class.).
*
* @param inputDirs list of directories to scan for documentation
- * @param blackList specify an optional blacklist file that list some rules that should not be
+ * @param denyList specify an optional denylist file that list some rules that should not be
* listed in the output.
* @throws BuildEncyclopediaDocException
* @throws IOException
* @return Map of rule class to rule documentation.
*/
- public Map<String, RuleDocumentation> collect(List<String> inputDirs, String blackList)
+ public Map<String, RuleDocumentation> collect(List<String> inputDirs, String denyList)
throws BuildEncyclopediaDocException, IOException {
RuleLinkExpander expander = new RuleLinkExpander(productName, /* singlePage */ false);
- return collect(inputDirs, blackList, expander);
+ return collect(inputDirs, denyList, expander);
}
/**
@@ -257,19 +262,19 @@
* <p>This method crawls the specified input directory (recursively calling itself for all
* subdirectories) and reads each Java source file using {@link SourceFileReader} to extract the
* raw rule and attribute documentation embedded in comments in a specific format. The extracted
- * documentation is then further processed, such as by
- * {@link BuildDocCollector#collect(List<String>, String, RuleLinkExpander), collect}, in order
- * to associate each rule's documentation with its attribute documentation.
+ * documentation is then further processed, such as by {@link
+ * BuildDocCollector#collect(List<String>, String, RuleLinkExpander), collect}, in order to
+ * associate each rule's documentation with its attribute documentation.
*
* <p>This method returns the following through its parameters: the set of Java source files
- * processed, a map of rule name to the source file it was extracted from, a map of rule name
- * to the documentation to the rule, and a multimap of attribute name to attribute documentation.
+ * processed, a map of rule name to the source file it was extracted from, a map of rule name to
+ * the documentation to the rule, and a multimap of attribute name to attribute documentation.
*
- * @param processedFiles The set of Java source files files that have already been processed
- * in order to avoid reprocessing the same file.
+ * @param processedFiles The set of Java source files files that have already been processed in
+ * order to avoid reprocessing the same file.
* @param ruleClassFiles Map of rule name to the source file it was extracted from.
* @param ruleDocEntries Map of rule name to rule documentation.
- * @param blackList The set of blacklisted rules whose documentation should not be extracted.
+ * @param denyList The set of denylisted rules whose documentation should not be extracted.
* @param attributeDocEntries Multimap of rule attribute name to attribute documentation.
* @param inputPath The File representing the file or directory to read.
* @throws BuildEncyclopediaDocException
@@ -279,9 +284,10 @@
Set<File> processedFiles,
Map<String, File> ruleClassFiles,
Map<String, RuleDocumentation> ruleDocEntries,
- Set<String> blackList,
+ Set<String> denyList,
ListMultimap<String, RuleDocumentationAttribute> attributeDocEntries,
- File inputPath) throws BuildEncyclopediaDocException, IOException {
+ File inputPath)
+ throws BuildEncyclopediaDocException, IOException {
if (processedFiles.contains(inputPath)) {
return;
}
@@ -292,7 +298,7 @@
sfr.readDocsFromComments();
for (RuleDocumentation d : sfr.getRuleDocEntries()) {
String ruleName = d.getRuleName();
- if (!blackList.contains(ruleName)) {
+ if (!denyList.contains(ruleName)) {
if (ruleDocEntries.containsKey(ruleName)
&& !ruleClassFiles.get(ruleName).equals(inputPath)) {
System.err.printf(
@@ -310,8 +316,13 @@
}
} else if (inputPath.isDirectory()) {
for (File childPath : inputPath.listFiles()) {
- collectDocs(processedFiles, ruleClassFiles, ruleDocEntries, blackList,
- attributeDocEntries, childPath);
+ collectDocs(
+ processedFiles,
+ ruleClassFiles,
+ ruleDocEntries,
+ denyList,
+ attributeDocEntries,
+ childPath);
}
}
diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaGenerator.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaGenerator.java
index 6934892..4e5413c 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaGenerator.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaGenerator.java
@@ -27,7 +27,7 @@
private static void printUsage(OptionsParser parser) {
System.err.println(
"Usage: docgen_bin -n product_name -p rule_class_provider (-i input_dir)+\n"
- + " [-o outputdir] [-b blacklist] [-1] [-h]\n\n"
+ + " [-o outputdir] [-b denylist] [-1] [-h]\n\n"
+ "Generates the Build Encyclopedia from embedded native rule documentation.\n"
+ "The product name (-n), rule class provider (-p) and at least one input_dir\n"
+ "(-i) must be specified.\n");
@@ -84,8 +84,7 @@
new MultiPageBuildEncyclopediaProcessor(
options.productName, createRuleClassProvider(options.provider));
}
- processor.generateDocumentation(
- options.inputDirs, options.outputDir, options.blacklist);
+ processor.generateDocumentation(options.inputDirs, options.outputDir, options.denylist);
} catch (BuildEncyclopediaDocException e) {
fail(e, false);
} catch (Throwable e) {
diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java
index 334e877..0cadb48 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java
@@ -73,14 +73,14 @@
public String outputDir;
@Option(
- name = "blacklist",
- abbrev = 'b',
- defaultValue = "",
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help = "A path to a file listing rules not to document."
- )
- public String blacklist;
+ name = "denylist",
+ oldName = "blacklist",
+ abbrev = 'b',
+ defaultValue = "",
+ documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+ effectTags = {OptionEffectTag.UNKNOWN},
+ help = "A path to a file listing rules not to document.")
+ public String denylist;
@Option(
name = "single_page",
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 d54379a3..e8f9184 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
@@ -62,15 +62,16 @@
}
/**
- * Collects and processes all the rule and attribute documentation in inputDirs and
- * generates the Build Encyclopedia into the outputDir.
+ * Collects and processes all the rule and attribute documentation in inputDirs and generates the
+ * Build Encyclopedia into the outputDir.
*
* @param inputDirs list of directory to scan for document in the source code
* @param outputRootDir output directory where to write the build encyclopedia
- * @param blackList optional path to a file listing rules to not document
+ * @param denyList optional path to a file listing rules to not document
*/
- public abstract void generateDocumentation(List<String> inputDirs, String outputDir,
- String blackList) throws BuildEncyclopediaDocException, IOException;
+ public abstract void generateDocumentation(
+ List<String> inputDirs, String outputDir, String denyList)
+ throws BuildEncyclopediaDocException, IOException;
/**
* POD class for containing lists of rule families separated into language-specific and generic as
diff --git a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
index b87d1d9..9bbdf63 100644
--- a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
@@ -30,20 +30,20 @@
}
/**
- * Collects and processes all the rule and attribute documentation in inputDirs and
- * generates the Build Encyclopedia into the outputDir.
+ * Collects and processes all the rule and attribute documentation in inputDirs and generates the
+ * Build Encyclopedia into the outputDir.
*
* @param inputDirs list of directory to scan for document in the source code
* @param outputDir output directory where to write the build encyclopedia
- * @param blackList optional path to a file listing rules to not document
+ * @param denyList optional path to a file listing rules to not document
*/
@Override
- public void generateDocumentation(List<String> inputDirs, String outputDir, String blackList)
+ public void generateDocumentation(List<String> inputDirs, String outputDir, String denyList)
throws BuildEncyclopediaDocException, IOException {
BuildDocCollector collector = new BuildDocCollector(productName, ruleClassProvider, false);
RuleLinkExpander expander = new RuleLinkExpander(productName, false);
- Map<String, RuleDocumentation> ruleDocEntries = collector.collect(
- inputDirs, blackList, expander);
+ Map<String, RuleDocumentation> ruleDocEntries =
+ collector.collect(inputDirs, denyList, expander);
warnAboutUndocumentedRules(
Sets.difference(ruleClassProvider.getRuleClassMap().keySet(), ruleDocEntries.keySet()));
diff --git a/src/main/java/com/google/devtools/build/docgen/ProtoFileBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/ProtoFileBuildEncyclopediaProcessor.java
index 6df86aa..03b776f 100644
--- a/src/main/java/com/google/devtools/build/docgen/ProtoFileBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/ProtoFileBuildEncyclopediaProcessor.java
@@ -34,12 +34,12 @@
* of RuleDocumentation objects.
*/
@Override
- public void generateDocumentation(List<String> inputDirs, String outputFile, String blackList)
+ public void generateDocumentation(List<String> inputDirs, String outputFile, String denyList)
throws BuildEncyclopediaDocException, IOException {
BuildDocCollector collector = new BuildDocCollector(productName, ruleClassProvider, false);
RuleLinkExpander expander = new RuleLinkExpander(productName, true);
Map<String, RuleDocumentation> ruleDocEntries =
- collector.collect(inputDirs, blackList, expander);
+ collector.collect(inputDirs, denyList, expander);
RuleFamilies ruleFamilies = assembleRuleFamilies(ruleDocEntries.values());
ImmutableList.Builder<RuleDocumentation> ruleDocsBuilder = new ImmutableList.Builder<>();
diff --git a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
index 395455b..883b141 100644
--- a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
@@ -30,20 +30,20 @@
}
/**
- * Collects and processes all the rule and attribute documentation in inputDirs and
- * generates the Build Encyclopedia into the outputDir.
+ * Collects and processes all the rule and attribute documentation in inputDirs and generates the
+ * Build Encyclopedia into the outputDir.
*
* @param inputDirs list of directory to scan for document in the source code
* @param outputDir output directory where to write the build encyclopedia
- * @param blackList optional path to a file listing rules to not document
+ * @param denyList optional path to a file listing rules to not document
*/
@Override
- public void generateDocumentation(List<String> inputDirs, String outputDir, String blackList)
+ public void generateDocumentation(List<String> inputDirs, String outputDir, String denyList)
throws BuildEncyclopediaDocException, IOException {
BuildDocCollector collector = new BuildDocCollector(productName, ruleClassProvider, false);
RuleLinkExpander expander = new RuleLinkExpander(productName, true);
- Map<String, RuleDocumentation> ruleDocEntries = collector.collect(
- inputDirs, blackList, expander);
+ Map<String, RuleDocumentation> ruleDocEntries =
+ collector.collect(inputDirs, denyList, expander);
warnAboutUndocumentedRules(
Sets.difference(ruleClassProvider.getRuleClassMap().keySet(), ruleDocEntries.keySet()));
RuleFamilies ruleFamilies = assembleRuleFamilies(ruleDocEntries.values());
diff --git a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
index 8bbc50c..312b791 100644
--- a/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
+++ b/src/main/java/com/google/devtools/build/docgen/SymbolFamilies.java
@@ -40,12 +40,12 @@
private final ImmutableMap<String, Object> bzlGlobals;
public SymbolFamilies(
- String productName, String provider, List<String> inputDirs, String blackList)
+ String productName, String provider, List<String> inputDirs, String denyList)
throws NoSuchMethodException, ClassPathException, InvocationTargetException,
IllegalAccessException, BuildEncyclopediaDocException, ClassNotFoundException,
IOException {
this.nativeRules =
- ImmutableList.copyOf(collectNativeRules(productName, provider, inputDirs, blackList));
+ ImmutableList.copyOf(collectNativeRules(productName, provider, inputDirs, denyList));
this.globals = Starlark.UNIVERSE;
ImmutableMap.Builder<String, Object> env = ImmutableMap.builder();
@@ -92,12 +92,12 @@
* and in BZL files as methods of the native package.
*/
private List<RuleDocumentation> collectNativeRules(
- String productName, String provider, List<String> inputDirs, String blackList)
+ String productName, String provider, List<String> inputDirs, String denyList)
throws NoSuchMethodException, InvocationTargetException, IllegalAccessException,
BuildEncyclopediaDocException, ClassNotFoundException, IOException {
ProtoFileBuildEncyclopediaProcessor processor =
new ProtoFileBuildEncyclopediaProcessor(productName, createRuleClassProvider(provider));
- processor.generateDocumentation(inputDirs, "", blackList);
+ processor.generateDocumentation(inputDirs, "", denyList);
return processor.getNativeRules();
}
