From d8706ac764fa00555d8c4a8f1510e0e702ce1c49 Mon Sep 17 00:00:00 2001
From: George Gastaldi <gegastaldi@gmail.com>
Date: Mon, 29 Jul 2013 15:40:04 -0300
Subject: [PATCH] Improved convert + ui READMEs

---
 convert/README.asciidoc | 78 +++++++++++++++++++++++++++++------------
 ui/README.asciidoc      |  2 ++
 2 files changed, 57 insertions(+), 23 deletions(-)

diff --git a/convert/README.asciidoc b/convert/README.asciidoc
index dd6c65801c..b351f567f1 100644
--- a/convert/README.asciidoc
+++ b/convert/README.asciidoc
@@ -1,6 +1,8 @@
 == Convert
 :idprefix: id_ 
 
+This addon provides *standalone* functionality, and *exports services* for use in other addons. 
+ 
 This addon enables the injection of converters for general purposes
 
 === Depends on
@@ -17,9 +19,9 @@ This addon enables the injection of converters for general purposes
 
 == Setup
 
-=== Service consumer
+This Addon requires the following installation steps.
 
-To consume exported services of this addon, you must add it a dependency in the *pom.xml* of your `forge-addon` classified artifact:
+=== Add configuration to pom.xml 
 
 [source,xml]
 ----
@@ -33,45 +35,75 @@ To consume exported services of this addon, you must add it a dependency in the
 
 == Features
 
-Injecting a specific converter:: Whenever you need to convert to a specific object, the converter addon is your pal:
+Injection of Converter APIs:: This addon also allows for injection of some of the core converter APIs into your
+objects. Below is a list of all injectable API types.
+
+[options="header"]
+|===
+|Injectable Type |Description
+
+|@Inject Converter<SOURCE,TARGET> converter;
+|A reference to a converter that is able to convert from the SOURCE type to TARGET type
+
+|@Inject ConverterFactory converterFactory;
+|A reference to the converter factory that produces Converter objects
+
+|===
+
+Creation of converters using ConverterGenerator:: By implementing the ConverterGenerator interface, your addon can automatically support usage of the Convert addon in other addons.
 
 [source,java]
 ----
-@Exported
-public interface AnAddonInterface
+public class DirectoryResourceConverterGenerator implements ConverterGenerator
 {
 
-}
+   @Inject
+   private Instance<DirectoryResourceConverter> converter;
 
-public class TestResultOne implements AnAddonInterface
-{
    @Override
-   public String toString()
+   public boolean handles(Class<?> source, Class<?> target)
    {
-      return "one";
+      return DirectoryResource.class.isAssignableFrom(target);
    }
-}
 
-public class TestResultTwo implements AnAddonInterface
-{
    @Override
-   public String toString()
+   public DirectoryResourceConverter generateConverter(Class<?> source, Class<?> target)
    {
-      return "two";
+      return converter.get();
+   }
+
+   @Override
+   public Class<DirectoryResourceConverter> getConverterType()
+   {
+      return DirectoryResourceConverter.class;
    }
 }
 
-public class ExampleAddon 
+
+
+@Singleton
+public class DirectoryResourceConverter extends AbstractConverter<Object, DirectoryResource>
 {
+   private final ResourceFactory resourceFactory;
 
    @Inject
-   private Converter<String, AnAddonInterface> converter;
-	
-   public void execute() {
-       AnAddonInterface one = converter.convert("one");
-       AnAddonInterface two  = converter.convert("two");
+   public DirectoryResourceConverter(ResourceFactory resourceFactory)
+   {
+      super(Object.class, DirectoryResource.class);
+      this.resourceFactory = resourceFactory;
    }
-}
 
+   @Override
+   public DirectoryResource convert(Object source)
+   {
+      File file;
+      if (source == null)
+         return null;
+      else if (source instanceof File)
+         file = (File) source;
+      else
+         file = new File(source.toString());
+      return resourceFactory.create(DirectoryResource.class, file);
+   }
+}
 ----
-
diff --git a/ui/README.asciidoc b/ui/README.asciidoc
index a32e2cdcf0..dc4681d747 100644
--- a/ui/README.asciidoc
+++ b/ui/README.asciidoc
@@ -1,6 +1,8 @@
 == UI (User Interface)
 :idprefix: id_ 
 
+This addon *exports services* for use in other addons. 
+
 This addon enables the creation of user interfaces making them agnostic to the underlying UI provider.
 
 In practice, that means that your code will run in any UI provider without requiring any changes.