--- a/langtools/test/tools/doclint/tidy/util/Main.java	Wed Sep 25 14:02:16 2013 -0700
+++ b/langtools/test/tools/doclint/tidy/util/Main.java	Wed Sep 25 14:04:24 2013 -0700
@@ -1,3 +1,27 @@
+/*
+ * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+
 package tidystats;
 
 import java.io.IOException;
@@ -17,6 +41,35 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Generate statistics from the files generated by tidy.sh.
+ *
+ * <p>The tidy.sh script is used to run tidy on all the HTML files
+ * in a directory, creating files in a new directory, and for each
+ * HTML file, it writes the console output from tidy into a file
+ * beside the fixed up file, with an additional .tidy extension.
+ *
+ * <p>This program will scan a directory for *.tidy files and
+ * analyze the messages reported by tidy, in order to generate a
+ * report with statistics on the various messages that were
+ * reported by tidy.
+ *
+ * <p>Typical usage:
+ * <pre>
+ * $ bash /path/to/tidy.sh /path/to/htmldir
+ * $ javac -d /path/to/classes /path/to/Main.java
+ * $ java -cp /path/to/classes tidystats.Main /path/to/htmldir.tidy
+ * </pre>
+ *
+ * <p>Internally, the program works by matching lines in the *.tidy
+ * files against a series of regular expressions that are used to
+ * categorize the messages.  The set of regular expressions was
+ * empirically determined by running the program on the output from
+ * running tidy.sh on all the generated JDK documentation. It is
+ * possible that tidy may generate more/different messages on other
+ * doc sets, in which case, the set of regexes in the program should
+ * be updated.
+ */
 public class Main {
     public static void main(String... args) throws IOException {
         new Main().run(args);

--- a/langtools/test/tools/doclint/tidy/util/tidy.sh	Wed Sep 25 14:02:16 2013 -0700
+++ b/langtools/test/tools/doclint/tidy/util/tidy.sh	Wed Sep 25 14:04:24 2013 -0700
@@ -1,6 +1,6 @@
-#!/bin/sh
+#!/bin/bash
 #
-# Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 #
 # This code is free software; you can redistribute it and/or modify it
@@ -23,6 +23,7 @@
 #
 
 # Run the "tidy" program over the files in a directory.
+# The "tidy" program must be on your PATH.
 #
 # Usage:
 #   sh tidy.sh <dir>