From 465974f540fcc846852a2ad48e50785af160a67c Mon Sep 17 00:00:00 2001
From: Yegor Kozlov <yegor@apache.org>
Date: Tue, 7 Feb 2012 08:17:21 +0000
Subject: [PATCH] improved javadoc on SXSSFWorkbook(XSSFWorkbook wb)

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1241373 13f79535-47bb-0310-9956-ffa450edef68
---
 .../poi/xssf/streaming/SXSSFWorkbook.java     | 37 ++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
index a9cdd954ec..a79f1aad02 100644
--- a/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
+++ b/src/ooxml/java/org/apache/poi/xssf/streaming/SXSSFWorkbook.java
@@ -77,7 +77,42 @@ public class SXSSFWorkbook implements Workbook
     public SXSSFWorkbook(){
     	this(null /*workbook*/);
     }
-    
+
+    /**
+     * Construct a workbook from a template.
+     * <p>
+     * There are three use-cases to use SXSSFWorkbook(XSSFWorkbook) :
+     * <ol>
+     *   <li>
+     *       Append new sheets to existing workbooks. You can open existing
+     *       workbook from a file or create on the fly with XSSF.
+     *   </li>
+     *   <li>
+     *       Append rows to existing sheets. The row number MUST be greater
+     *       than max(rownum) in the template sheet.
+     *   </li>
+     *   <li>
+     *       Use existing workbook as a template and re-use global objects such
+     *       as cell styles, formats, images, etc.
+     *   </li>
+     * </ol>
+     * All three use cases can work in a combination.
+     * </p>
+     * What is not supported:
+     * <ul>
+     *   <li>
+     *   Access initial cells and rows in the template. After constructing
+     *   SXSSFWorkbook(XSSFWorkbook) all internal windows are empty and
+     *   SXSSFSheet@getRow and SXSSFRow#getCell return null.
+     *   </li>
+     *   <li>
+     *    Override existing cells and rows. The API silently allows that but
+     *    the output file is invalid and Excel cannot read it.
+     *   </li>
+     * </ul>
+     *
+     * @param workbook  the template workbook
+     */
     public SXSSFWorkbook(XSSFWorkbook workbook){
     	this(workbook, DEFAULT_WINDOW_SIZE);
     }