diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java b/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
index da7ebb866..47b2fc749 100644
--- a/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
+++ b/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
@@ -49,6 +49,13 @@ public void setAttributes(Map<String, Object> attributes) {
         this.options.put(ATTRIBUTES, attributes);
     }
 
+    /**
+     * Toggle including header and footer into the output.
+     *
+     * @param headerFooter If <code>true</true>, include header and footer into the output,
+     *                     otherwise exclude them. This overrides any output-specific defaults.
+     *
+     */
     public void setHeaderFooter(boolean headerFooter) {
         this.options.put(HEADER_FOOTER, headerFooter);
     }
@@ -67,10 +74,28 @@ public void setTemplateEngine(String templateEngine) {
         this.options.put(TEMPLATE_ENGINE, templateEngine);
     }
 
+    /**
+     * Enable writing output to a file. The file includes header and footer by default.
+     *
+     * @param toFile The path to the output file. If the path is not absolute, it is
+     *               interpreted relative to what was set via {@link #setToDir()}
+     *               or {@link #setBaseDir()}, in that order.
+     *
+     */
     public void setToFile(String toFile) {
         this.options.put(TO_FILE, toFile);
     }
 
+    /**
+     * Toogle writing output to a file.
+     *
+     * @param toFile If <code>true</true>, write output to a file in the same directory
+     *               as the input file, including header and footer into the output. If
+     *               <code>false</code>, return output as a string without any header or
+     *               footer. The default header and footer visibility can be overridden
+     *               using {@link #setHeaderFooter()}.
+     *
+     */
     public void setToFile(boolean toFile) {
         this.options.put(TO_FILE, toFile);
     }
diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java b/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java
index 18708499e..be57b4ab7 100644
--- a/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java
+++ b/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java
@@ -155,10 +155,13 @@ public OptionsBuilder attributes(AttributesBuilder attributes) {
     }
 
     /**
-     * Sets to file value. This is the destination file name.
+     * Sets to file value. This toggles writing output to a file or returning output
+     * as a string. If writing to a string, the header and footer are omitted from the
+     * output by default.
      * 
      * @param toFile
-     *            name of output file.
+     *            <code>true</code> to write output to a file, <code>false</code>
+     *            to write output to a string.
      * @return this instance.
      */
     public OptionsBuilder toFile(boolean toFile) {