svn commit: r1058061 - /maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java

[lt...@apache.org]

Author: ltheussl
Date: Wed Jan 12 10:48:43 2011
New Revision: 1058061

URL: http://svn.apache.org/viewvc?rev=1058061&view=rev
Log:
Javadoc clarifications. The docs for resolvePaths caused some confusion, it seems the original intent was to resolve links (ie make them absolute with the given base) but the actual implementation in DefaultDecorationModelInheritanceAssembler really did the opposite, ie relativize the links wrt the given base. See MSITE-62.

Modified:
    maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java

Modified: maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java
URL: http://svn.apache.org/viewvc/maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java?rev=1058061&r1=1058060&r2=1058061&view=diff
==============================================================================
--- maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java (original)
+++ maven/doxia/doxia-sitetools/trunk/doxia-decoration-model/src/main/java/org/apache/maven/doxia/site/decoration/inheritance/DecorationModelInheritanceAssembler.java Wed Jan 12 10:48:43 2011
@@ -35,11 +35,23 @@ public interface DecorationModelInherita
     /**
      * Manage inheritance of the decoration model between a parent and child.
      *
+     * Any relative links in the parent model will be re-based to work from the merged child
+     * model, otherwise no content from either the parent or child model should be modifiedjav.
+     *
      * @param name a name, used for breadcrumb.
+     *      If the parent model contains breadcrumbs and the child doesn't,
+     *      a child breadcrumb will be added to the merged model with this name. Not null.
      * @param child the child DecorationModel to be merged with parent.
-     * @param parent the parent DecorationModel not null.
+     *      Not null. If parent == null, the child is unchanged, otherwise
+     *      child will contain the merged model upon exit.
+     * @param parent the parent DecorationModel. Unchanged upon exit.
+     *      May be null in which case the child is not changed.
      * @param childBaseUrl the child base URL.
+     *      May be null, in which case relative links inherited from the parent
+     *      will not be resolved in the merged child.
      * @param parentBaseUrl the parent base URL.
+     *      May be null, in which case relative links inherited from the parent
+     *      will not be resolved in the merged child.
      */
     void assembleModelInheritance( String name, DecorationModel child, DecorationModel parent,
                                    String childBaseUrl, String parentBaseUrl );
@@ -47,8 +59,15 @@ public interface DecorationModelInherita
     /**
      * Resolve relative paths for a DecorationModel given a base URL.
      *
+     * Note that 'resolve' here means 'relativize' in the sense of
+     * {@link java.net.URI#relativize(java.net.URI)}, ie if any link in the decoration model
+     * has a base URL that is equal to the given baseUrl, it is replaced by a relative link
+     * with respect to that base.
+     *
      * @param decoration  the DecorationModel.
+     *      Not null.
      * @param baseUrl the base URL.
+     *      May be null in which case the decoration model is unchanged.
      */
     void resolvePaths( DecorationModel decoration, String baseUrl );
 }