From 07fed407fce84dc9c0f7cf203eb8266255ebad7b Mon Sep 17 00:00:00 2001
From: Sebastian Schuberth <sschuberth@gmail.com>
Date: Fri, 19 Aug 2016 17:52:13 +0200
Subject: [PATCH] Improve the toFile documentation about file vs. string output

Closes #502.
---
 .../main/java/org/asciidoctor/Options.java    | 25 +++++++++++++++++++
 .../java/org/asciidoctor/OptionsBuilder.java  |  7 ++++--
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java b/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
index a4b28c169..cc49d861a 100644
--- a/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
+++ b/asciidoctorj-core/src/main/java/org/asciidoctor/Options.java
@@ -50,6 +50,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);
     }
@@ -68,6 +75,14 @@ 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);
     }
@@ -76,6 +91,16 @@ public void setToStream(OutputStream toStream) {
         this.options.put(TO_FILE, toStream);
     }
 
+    /**
+     * 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 8641e9f53..c0d703c67 100644
--- a/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java
+++ b/asciidoctorj-core/src/main/java/org/asciidoctor/OptionsBuilder.java
@@ -156,10 +156,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) {