Improved docs.

Author: nedtwigg

README.md

@@ -22,7 +22,7 @@ output = [
 [![Travis CI](https://travis-ci.org/diffplug/durian.svg?branch=master)](https://travis-ci.org/diffplug/durian)
 <!---freshmark /shields -->
 
-Generating URL's for the buttons above is tricky.  Once they're generated, it's hard to keep them up-to-date as new versions are released.  FreshMark solves the "Markdown with variables" problem by embedding tiny JavaScript programs into the comments of your Markdown, which statically generate the rest of the document.  By running these programs as part of your build script, your project's documentation will always stay up-to-date.
+Generating URL's for the buttons above is tricky.  Once they're generated, it's hard to keep them up-to-date as new versions are released.  FreshMark solves the "Markdown with variables" problem by embedding tiny JavaScript SCRIPTs into the comments of your Markdown, which statically generate the rest of the document.  By running these SCRIPTs as part of your build script, your project's documentation will always stay up-to-date.
 
 Here is what the code looks like for the shields at the top of this document:
 
@@ -51,20 +51,20 @@ To run FreshMark on some text, call [FreshMark.compile()](https://diffplug.githu
 
 ## How it works
 
-FreshMark has three pieces, `SECTION`, `PROGRAM`, and `INPUT`.  They are parsed as shown below:
+FreshMark has three pieces, `SECTION`, `SCRIPT`, and `BODY`.  They are parsed as shown below:
 
 ```javascript
 <!---freshmark SECTION (identifier)
-PROGRAM (javascript)
+SCRIPT (javascript)
 -->
-INPUT (markdown)
+BODY (markdown)
 <!---freshmark /SECTION -->
 ```
 
-When `PROGRAM` is run, there are two magic variables:
+When `SCRIPT` is run, there are two magic variables:
 
-* `input` - This is everything inside of INPUT (guaranteed to have only unix newlines at runtime)
-* `output` - The script must assign to this variable.  FreshMark will generate a new string where the `INPUT` section has been replaced with this value.
+* `input` - This is everything inside of BODY (guaranteed to have only unix newlines at runtime)
+* `output` - The script must assign to this variable.  FreshMark will generate a new string where the `BODY` section has been replaced with this value.
 
 Only four functions are provided:
 
@@ -79,8 +79,8 @@ It's full ECMAScript 5.1, so you can define any other functions you like, but th
 
 When you run FreshMark, you can supply it with a map of key-value pairs using the command line or via a properties file.  If you're running FreshMark from a build system plugin such as Gradle, then all of your project's metadata will automatically be supplied.  These key-value pairs are used in the following way:
 
-* Before `PROGRAM` is executed, any `{{key}}` templates will be substituted with their corresponding value.
-* When `PROGRAM` is executed, all of these key-value pairs are available as variables.
+* Before `SCRIPT` is executed, any `{{key}}` templates will be substituted with their corresponding value.
+* When `SCRIPT` is executed, all of these key-value pairs are available as variables.
 
 ## How to run it
 

src/main/java/com/diffplug/freshmark/CommentScript.java

@@ -47,8 +47,8 @@
  * you must provide:
  * <ul>
  * <li>A {@link Parser} to split the comment text from the body text.</li>
- * <li>{@link #keyToValue} - defines how template keys in the script string are transformed into values</li>
- * <li>{@link #setupScriptEngine} - initializes any functions or variables which should be available to the script</li>
+ * <li>{@link #keyToValue} - defines how template keys in the script string are transformed into values.</li>
+ * <li>{@link #setupScriptEngine} - initializes any functions or variables which should be available to the script.</li>
  * </ul>
  * @see FreshMark
  */

src/main/java/com/diffplug/freshmark/FreshMark.java

@@ -30,7 +30,10 @@
 import com.diffplug.jscriptbox.JScriptBox;
 import com.diffplug.jscriptbox.Language;
 
-/** The default implementation. */
+/**
+ * FreshMark is designed to generate and modify
+ * markdown using javascript.
+ */
 public class FreshMark extends CommentScript {
 	private static final String INTRON = "<!---freshmark";
 	private static final String EXON = "-->";
@@ -70,17 +73,17 @@ protected String keyToValue(String section, String key) {
 	// built-in functions //
 	////////////////////////
 	/** Generates a markdown link. */
-	static String link(String text, String url) {
+	public static String link(String text, String url) {
 		return "[" + text + "](" + url + ")";
 	}
 
 	/** Generates a markdown image. */
-	static String image(String altText, String url) {
+	public static String image(String altText, String url) {
 		return "!" + link(altText, url);
 	}
 
 	/** Generates shields using <a href="http://shields.io/">shields.io</a>. */
-	static String shield(String altText, String subject, String status, String color) {
+	public static String shield(String altText, String subject, String status, String color) {
 		return image(altText, "https://img.shields.io/badge/" + shieldEscape(subject) + "-" + shieldEscape(status) + "-" + shieldEscape(color) + ".svg");
 	}
 
@@ -91,7 +94,7 @@ private static String shieldEscape(String raw) {
 	}
 
 	/** Replaces after prefix and before delimiter with replacement.  */
-	static String prefixDelimiterReplace(String input, String prefix, String delimiter, String replacement) {
+	public static String prefixDelimiterReplace(String input, String prefix, String delimiter, String replacement) {
 		StringBuilder builder = new StringBuilder(input.length() * 3 / 2);
 		int lastElement = 0;
 		Pattern pattern = Pattern.compile("(.*?" + Pattern.quote(prefix) + ")(.*?)(" + Pattern.quote(delimiter) + ")", Pattern.DOTALL);

src/main/java/com/diffplug/freshmark/Parser.java

@@ -17,7 +17,14 @@
 
 import java.util.function.Consumer;
 
-/** A format defined by "tag start" and "tag end" chunks of text. */
+/**
+ * Parser splits text into tags and body sections, passes
+ * pairs of matching sections to a {@link SectionCompiler}, then
+ * combines that output with the original document to generate
+ * the final output.
+ * 
+ * @see {@link ParserIntronExtron}
+ */
 public abstract class Parser {
 	/** Interface which can compile a single section of a FreshMark document. */
 	@FunctionalInterface
@@ -36,13 +43,13 @@ protected interface ChunkHandler {
 	}
 
 	/**
-	 * Given an input string, parses out the body sections from the tag sections.
+	 * Given an input string, parses out the body sections from the tags section.
 	 * 
-	 * @param rawInput 	the raw input string
+	 * @param fullInput	the raw input string
 	 * @param body		called for every chunk of text outside a tag
 	 * @param tag		called for every chunk of text inside a tag
 	 */
-	protected abstract void bodyAndTags(String rawInput, ChunkHandler body, ChunkHandler tag);
+	protected abstract void bodyAndTags(String fullInput, ChunkHandler body, ChunkHandler tag);
 
 	/**
 	 * Reassembles a section/script/output chunk back into

src/main/java/com/diffplug/freshmark/ParserIntronExon.java

@@ -18,7 +18,11 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
-/** A format defined by "tag start" and "tag end" chunks of text. */
+/**
+ * A parser defined by "intron" and "extron" chunks of text.
+ * 
+ * @see {@link FreshMark}
+ */
 public class ParserIntronExon extends Parser {
 	final String intron, exon;
 	final Pattern pattern;
@@ -76,23 +80,23 @@ protected void bodyAndTags(String rawInput, ChunkHandler body, ChunkHandler tag)
 	 * 
 	 * @param section
 	 * @param script
-	 * @param output
+	 * @param body
 	 * @return
 	 */
 	@Override
-	protected String reassemble(String section, String script, String output) {
+	protected String reassemble(String section, String script, String body) {
 		// make sure that the compiled output starts and ends with a newline,
 		// so that the tags stay separated separated nicely
-		if (!output.startsWith("\n")) {
-			output = "\n" + output;
+		if (!body.startsWith("\n")) {
+			body = "\n" + body;
 		}
-		if (!output.endsWith("\n")) {
-			output = output + "\n";
+		if (!body.endsWith("\n")) {
+			body = body + "\n";
 		}
 		return intron + " " + section + "\n" +
 				script +
 				exon +
-				output +
+				body +
 				intron + " /" + section + " " + exon;
 	}
 }