svn commit: r1695232 - /sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext

[bd...@apache.org]

Author: bdelacretaz
Date: Tue Aug 11 08:56:37 2015
New Revision: 1695232

URL: http://svn.apache.org/r1695232
Log:
Clarify deprecation of two-args method

Modified:
    sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext

Modified: sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext?rev=1695232&r1=1695231&r2=1695232&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext (original)
+++ sling/site/trunk/content/documentation/the-sling-engine/wrap-or-decorate-resources.mdtext Tue Aug 11 08:56:37 2015
@@ -12,22 +12,25 @@ To add a resource decorator just registe
 
     :::java
     interface ResourceDecorator {
+        /** Optionally decorate the supplied Resource */
         Resource decorate(Resource)
     
+        /** Only called if using older versions of Sling, see below */
         @Deprecated
         Resource decorate(Resource, HttpServletRequest)
     } 
 
 
 The registered decorators will be called from the resource resolver for each resource returned. 
-If the service decorates the resource it should return the new resource. If the service does not want to decorate the resource, it should return the original resource or null. 
+If the service decorates the resource it should return the new resource (often using a `ResourceWrapper` to wrap the original Resource). 
+If the service does not want to decorate the resource, it should return the original resource or null. 
 
-The two-argument `decorate` method will not be invoked, starting with version 2.1.0 of the JCR Resource bundle. Implementors of this interface targeting both newer and older versions of this bundle are advised to implement this method with:
+Starting with version 2.1.0 of the JCR Resource bundle, the two-argument `decorate` method is not called anymore. 
+Implementors of this interface targeting both newer and older versions of this bundle are advised to implement this method as:
 
     :::java
     public Resource decorate(Resource resource, HttpServletRequest request) {
         return this.decorate(resource);
     }
 
-
-And use some other method (e.g. a `ThreadLocal`) to obtain the current request if necessary.
\ No newline at end of file
+And use some other mechanism (e.g. a `ThreadLocal`) to obtain the current request if necessary.