Annotate the public/confidential/shared parts of the BE template.
Rewrite some examples that used internal labels to be safe for external
version. Also remove some obsolete parts such as no-longer existent Make
variables.
--
MOS_MIGRATED_REVID=87241538
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 fb52a4c..e80b2c5 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
@@ -59,21 +59,16 @@
*/
public void generateDocumentation(String[] inputDirs, String outputRootDir)
throws BuildEncyclopediaDocException, IOException {
- BufferedWriter bw = null;
File buildEncyclopediaPath = setupDirectories(outputRootDir);
- try {
- bw = new BufferedWriter(new FileWriter(buildEncyclopediaPath));
+ try (BufferedWriter bw = new BufferedWriter(new FileWriter(buildEncyclopediaPath))) {
bw.write(DocgenConsts.HEADER_COMMENT);
+ bw.write("\n"); // for the benefit of the block-beginning comment at the top of the template
Set<RuleDocumentation> ruleDocEntries = collectAndProcessRuleDocs(inputDirs, false);
writeRuleClassDocs(ruleDocEntries, bw);
+ bw.write("\n"); // for the benefit of the block-beginning comment at the top of the template
bw.write(SourceFileReader.readTemplateContents(DocgenConsts.FOOTER_TEMPLATE));
-
- } finally {
- if (bw != null) {
- bw.close();
- }
}
}
@@ -196,6 +191,7 @@
}
}
+ bw.write("\n"); // for the benefit of the block-beginning comment at the top of the template
bw.write(SourceFileReader.readTemplateContents(DocgenConsts.HEADER_TEMPLATE,
generateBEHeaderMapping(docEntries)));
@@ -205,6 +201,7 @@
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 a2e7583..161d7b6 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -13,6 +13,8 @@
// limitations under the License.
package com.google.devtools.build.docgen;
+import com.google.common.base.Joiner;
+import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;
import com.google.devtools.build.lib.util.FileType;
import com.google.devtools.build.lib.util.FileTypeSet;
@@ -62,13 +64,16 @@
public static final String FLAG_DEPRECATED = "DEPRECATED";
public static final String FLAG_GENERIC_RULE = "GENERIC_RULE";
- public static final String HEADER_COMMENT =
- "<!DOCTYPE html>\n"
- + "<!--\n"
- + " This document is synchronized with Blaze releases.\n"
- + " To edit, submit changes to the Blaze source code.\n"
- + " Generated by: blaze build java/com/google/devtools/build/docgen:build-encyclopedia.html\n"
- + "-->\n";
+ public static final String HEADER_COMMENT = Joiner.on("\n").join(ImmutableList.<String>of(
+ "<!-- begin-block:shared -->",
+ "<!DOCTYPE html>",
+ "<!--",
+ " This document is synchronized with Blaze releases.",
+ " To edit, submit changes to the Blaze source code.",
+ "-->",
+ "",
+ "<!-- begin-block:internal -->",
+ "<!-- Generated by //java/com/google/devtools/build/docgen:build-encyclopedia.html -->"));
public static final String BUILD_ENCYCLOPEDIA_NAME = "build-encyclopedia.html";
