From c3405caac549521de3ff36018beaeb07a0176251 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Fri, 1 Mar 2002 16:29:15 +0000 Subject: [PATCH] JavaDoc changes. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271641 13f79535-47bb-0310-9956-ffa450edef68 --- .../apache/tools/ant/RuntimeConfigurable.java | 87 +++++++++++++++---- 1 file changed, 72 insertions(+), 15 deletions(-) diff --git a/src/main/org/apache/tools/ant/RuntimeConfigurable.java b/src/main/org/apache/tools/ant/RuntimeConfigurable.java index 6b842cc01..6787a46c6 100644 --- a/src/main/org/apache/tools/ant/RuntimeConfigurable.java +++ b/src/main/org/apache/tools/ant/RuntimeConfigurable.java @@ -1,7 +1,7 @@ /* * The Apache Software License, Version 1.1 * - * Copyright (c) 2000-2001 The Apache Software Foundation. All rights + * Copyright (c) 2000-2002 The Apache Software Foundation. All rights * reserved. * * Redistribution and use in source and binary forms, with or without @@ -61,81 +61,138 @@ import org.xml.sax.AttributeList; import org.xml.sax.helpers.AttributeListImpl; /** - * Wrapper class that holds the attributes of a Task (or elements - * nested below that level) and takes care of configuring that element - * at runtime. + * Wrapper class that holds the attributes of an element, its children, and + * any text within it. It then takes care of configuring that element at + * runtime. * * @author Stefan Bodewig */ public class RuntimeConfigurable { + /** Name of the element to configure. */ private String elementTag = null; + /** List of child element wrappers. */ private Vector children = new Vector(); + /** The element to configure. */ private Object wrappedObject = null; + /** XML attributes for the element. */ private AttributeList attributes; + /** Text appearing within the element. */ private StringBuffer characters = new StringBuffer(); /** - * @param proxy The element to wrap. + * Sole constructor creating a wrapper for the specified object. + * + * @param proxy The element to configure. Must not be null. + * @param elementTag The tag name generating this element. + * Should not be null. */ public RuntimeConfigurable(Object proxy, String elementTag) { wrappedObject = proxy; this.elementTag = elementTag; } + /** + * Sets the element to configure. This is used when the real type of + * an element isn't known at the time of wrapper creation. + * + * @param proxy The element to configure. Must not be null. + */ void setProxy(Object proxy) { wrappedObject = proxy; } /** - * Set's the attributes for the wrapped element. + * Sets the attributes for the wrapped element. + * + * @param attributes List of attributes defined in the XML for this + * element. May be null. */ public void setAttributes(AttributeList attributes) { this.attributes = new AttributeListImpl(attributes); } /** - * Returns the AttributeList of the wrapped element. + * Returns the list of attributes for the wrapped element. + * + * @return An AttributeList representing the attributes defined in the + * XML for this element. May be null. */ public AttributeList getAttributes() { return attributes; } /** - * Adds child elements to the wrapped element. + * Adds a child element to the wrapped element. + * + * @param child The child element wrapper to add to this one. + * Must not be null. */ public void addChild(RuntimeConfigurable child) { children.addElement(child); } /** - * Returns the child with index index. + * Returns the child wrapper at the specified position within the list. + * + * @param index The index of the child to return. + * + * @return The child wrapper at position index within the + * list. */ RuntimeConfigurable getChild(int index) { return (RuntimeConfigurable) children.elementAt(index); } /** - * Add characters from #PCDATA areas to the wrapped element. + * Adds characters from #PCDATA areas to the wrapped element. + * + * @param data Text to add to the wrapped element. + * Should not be null. */ public void addText(String data) { characters.append(data); } /** - * Add characters from #PCDATA areas to the wrapped element. + * Adds characters from #PCDATA areas to the wrapped element. + * + * @param buf A character array of the text within the element. + * Must not be null. + * @param start The start element in the array. + * @param count The number of characters to read from the array. + * */ - public void addText(char[] buf, int start, int end) { - addText(new String(buf, start, end)); + public void addText(char[] buf, int start, int count) { + addText(new String(buf, start, count)); } + /** + * Returns the tag name of the wrapped element. + * + * @return The tag name of the wrapped element. This is unlikely + * to be null, but may be. + */ public String getElementTag() { return elementTag; } - /** - * Configure the wrapped element and all children. + * Configures the wrapped element and all its children. + * The attributes and text for the wrapped element are configured, + * and then each child is configured and added. Each time the + * wrapper is configured, the attributes and text for it are + * reset. + * + * If the element has an id attribute, a reference + * is added to the project as well. + * + * @param p The project containing the wrapped element. + * Must not be null. + * + * @exception BuildException if the configuration fails, for instance due + * to invalid attributes or children, or text being added to + * an element which doesn't accept it. */ public void maybeConfigure(Project p) throws BuildException { String id = null;