From ed0166eaaeb27ba767498944fc4c212ca0b96c68 Mon Sep 17 00:00:00 2001
From: Costin Leau <cleau@vmware.com>
Date: Wed, 18 Jul 2012 16:18:41 +0300
Subject: [PATCH] update docs

---
 .../reference/dev-guide/dev-spring-shell.xml    | 14 ++++++++++----
 .../docbook/samples/simple-application.xml      | 17 ++++++-----------
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml b/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml
index 287783e6..b3f71916 100644
--- a/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml
+++ b/docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml
@@ -40,8 +40,10 @@ public class HelloWorldCommands implements CommandMarker {
   <section>
     <title>Logging</title>
 
-    <para>Logging is done using JDK logging. Simply add a LOG declaration as
-    shown below to use a logger.</para>
+    <para>Logging is currently done using JDK logging. Due to the intrincacies of console, JLine and Ansi
+    handling, it is generally advised to display messages as return values to the method commands. However,
+    when logging is required, the typical JDK logger declaration should suffice.
+    </para>
 
     <programlisting language="java">@Component
 public class HelloWorldCommands implements CommandMarker {
@@ -98,12 +100,12 @@ public class HelloWorldCommands implements CommandMarker {
   }
 
   @CliCommand(value = "hw simple", help = "Print a simple hello world message")
-  public void simple(
+  public String simple(
     @CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final String message,
     @CliOption(key = { "location" }, mandatory = false, help = "Where you are saying hello", specifiedDefaultValue="At work") 
                  final String location) {
 
-    LOG.info("Message = [" + message + "] Location = [" + location + "]");
+    return "Message = [" + message + "] Location = [" + location + "]";
 
   }
 }</programlisting>
@@ -141,6 +143,10 @@ public class HelloWorldCommands implements CommandMarker {
     register your own implementation of the
     <interfacename>org.springframework.shell.core.Converter</interfacename>
     interface with the container in your plugin.</para>
+    
+    <para>Note that the the method return argument can be non-void - in our example, it is the actual
+    message we want to display. Whenever an object is returned, the shell will display its toString()
+    representation.</para>
   </section>
 
   <section>
diff --git a/docs/src/reference/docbook/samples/simple-application.xml b/docs/src/reference/docbook/samples/simple-application.xml
index 634121d8..16e0ab1d 100644
--- a/docs/src/reference/docbook/samples/simple-application.xml
+++ b/docs/src/reference/docbook/samples/simple-application.xml
@@ -35,9 +35,6 @@
 
     <programlisting language="java">package org.springframework.shell.samples.helloworld.commands;
 
-
-import java.util.logging.Logger;
-
 import org.springframework.shell.core.CommandMarker;
 import org.springframework.shell.core.annotation.CliAvailabilityIndicator;
 import org.springframework.shell.core.annotation.CliCommand;
@@ -47,8 +44,6 @@ import org.springframework.stereotype.Component;
 @Component
 public class HelloWorldCommands implements CommandMarker {
 	
-	protected final Logger LOG = Logger.getLogger(getClass().getName());
-	
 	private boolean simpleCommandExecuted = false;
 	
 	@CliAvailabilityIndicator({"hw simple"})
@@ -67,27 +62,27 @@ public class HelloWorldCommands implements CommandMarker {
 	}
 		
 	@CliCommand(value = "hw simple", help = "Print a simple hello world message")
-	public void simple(
+	public String simple(
 		@CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final String message,
 		@CliOption(key = { "location" }, mandatory = false, help = "Where you are saying hello", specifiedDefaultValue="At work") final String location) {		
-		LOG.info("Message = [" + message + "] Location = [" + location + "]");
 		simpleCommandExecuted = true;
+		return "Message = [" + message + "] Location = [" + location + "]";
 	}
 	
 	@CliCommand(value = "hw complex", help = "Print a complex hello world message")
-	public void hello(
+	public String hello(
 		@CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final String message,
 		@CliOption(key = { "name1"}, mandatory = true, help = "Say hello to the first name") final String name1,
 		@CliOption(key = { "name2" }, mandatory = true, help = "Say hello to a second name") final String name2,
 		@CliOption(key = { "time" }, mandatory = false, specifiedDefaultValue="now", help = "When you are saying hello") final String time,
 		@CliOption(key = { "location" }, mandatory = false, help = "Where you are saying hello") final String location) {		
-		LOG.info("Hello " + name1 + " and " + name2 + ". Your special message is "  + message + ". time=[" + time + "] location=[" + location + "]");
+		return "Hello " + name1 + " and " + name2 + ". Your special message is "  + message + ". time=[" + time + "] location=[" + location + "]";
 	}
 	
 	@CliCommand(value = "hw enum", help = "Print a simple hello world message from an enumerated value")
-	public void eenum(
+	public String eenum(
 		@CliOption(key = { "message" }, mandatory = true, help = "The hello world message") final MessageType message){		
-		LOG.info("Hello.  You special enumerated message is " + message);
+		return "Hello.  Your special enumerated message is " + message;
 	}
 	
 	enum MessageType {