/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.xwiki.rendering.block;

import java.util.List;

import org.xwiki.rendering.listener.Listener;

/**
 * Represents an element of a XWiki Document's content. For example there are Blocks for Paragraphs, Bold parts,
 * Sections, Links, etc. A block has a parent and can have children too for Blocks which are wrapper around other
 * blocks (e.g. Paragraph blocks, List blocks, Bold blocks).
 *
 * @version $Id$
 * @since 1.5M2
 */
public interface Block
{
    void traverse(Listener listener);
    
    void addChild(Block block);
    
    void addChildren(List<? extends Block> blocks);
    
    Block getParent();
    
    void setParent(Block parentBlock);
    
    List<Block> getChildren();
    
    Block getRoot();
   
    <T extends Block> List<T> getChildrenByType(Class<T> blockClass);
}

@@ -1351,16 +1351,408 @@
 Block%0A%7B%0A
+    /**%0A     * Let the block send %7B@link Listener%7D events corresponding to its content. For example a Paragraph block will%0A     * send the %7B@link org.xwiki.rendering.listener.Listener#beginParagraph()%7D and%0A     * %7B@link org.xwiki.rendering.listener.Listener#endParagraph()%7D events when this method is called.%0A     *%0A     * @param listener the listener to which to send the events to.%0A     */%0A
     void
@@ -1781,20 +1781,236 @@
 tener);%0A
+%0A
     
+/**%0A     * Helper method to add a single child block to the current block. For adding several blocks at once use%0A     * %7B@link #addChildren(java.util.List)%7D.%0A     *%0A     * @param block the child block to add%0A     */
 %0A    voi
@@ -2030,28 +2030,283 @@
 ock block);%0A
+%0A
     
+/**%0A     * Adds several children blocks to the current block. For example a bold sentence is made up of a Bold block%0A     * to which the different words making up the text have been added to.%0A     *%0A     * @param blocks the children blocks to add%0A     */
 %0A    void ad
@@ -2346,20 +2346,179 @@
 locks);%0A
+%0A
     
+/**%0A     * Get the parent block. All blocks have a parent and the top level parent is the %7B@link XDOM%7D object.%0A     * %0A     * @return the parent block%0A     */
 %0A    Blo
@@ -2529,28 +2529,120 @@
 etParent();%0A
+%0A
     
+/**%0A     * Sets the parent block.%0A     *%0A     * @param parentBlock the parent block%0A     */
 %0A    void se
@@ -2669,20 +2669,149 @@
 Block);%0A
+%0A
     
+/**%0A     * Gets all children blocks.%0A     *%0A     * @return the children blocks%0A     * @see #addChildren(java.util.List) %0A     */
 %0A    Lis
@@ -2838,37 +2838,312 @@
 ();%0A
+%0A
     
-%0A    Block getRoot();%0A   
+/**%0A     * Gets the top level Block.%0A     *%0A     * @return the top level Block%0A     */%0A    Block getRoot();%0A%0A    /**%0A     * Gets all the Blocks in the tree which are of the passed Block class.%0A     *%0A     * @param blockClass the block class to look for%0A     * @return all the matching blocks%0A     */
 %0A   

Rewrite the Rendering engine