You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2003/09/02 18:38:14 UTC
cvs commit: jakarta-tapestry/doc/src/ContributorsGuide ContributorsGuide.xml
hlship 2003/09/02 09:38:14
Modified: doc/src/ComponentReference Insert.html
doc/src/UsersGuide template.xml TapestryUsersGuide.xml
doc/src/ContributorsGuide ContributorsGuide.xml
Log:
Update documentation.
Revision Changes Path
1.17 +6 -2 jakarta-tapestry/doc/src/ComponentReference/Insert.html
Index: Insert.html
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/ComponentReference/Insert.html,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- Insert.html 26 Jul 2003 02:18:27 -0000 1.16
+++ Insert.html 2 Sep 2003 16:38:13 -0000 1.17
@@ -119,6 +119,10 @@
<td> </td>
<td>If specified, then the output is wrapped in an HTML <span> tag,
using the value specified as the CSS class.
+
+ <p>
+ Informal parameters are only rendered if a class is specified.
+ </p>
</td>
</tr>
<tr>
@@ -141,7 +145,7 @@
</tr>
</table>
<P>Body: <STRONG>removed</STRONG><BR>Informal parameters:
- <STRONG>forbidden</STRONG>
+ <STRONG>allowed</STRONG>
<br>
Reserved
parameters: <EM>none</EM> </P>
1.2 +6 -6 jakarta-tapestry/doc/src/UsersGuide/template.xml
Index: template.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/template.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- template.xml 18 Aug 2003 22:25:19 -0000 1.1
+++ template.xml 2 Sep 2003 16:38:13 -0000 1.2
@@ -89,7 +89,7 @@
<para>
Usually, about 90% of a template is ordinary HTML markup. Hidden inside that markup are particular tags that
-are placeholders for Tapestry components; these tags are recognized by the presence of the &jwc; attribute. "JWC"
+are placeholders for Tapestry components; these tags are recognized by the presence of the &jwcid; attribute. "JWC"
is short for "Java Web Component", and was chosen as the "magic" attribute so as not to conflict with any real HTML attribute.
</para>
@@ -106,7 +106,7 @@
<title>Components in Templates</title>
<para>
-Components can be placed anywhere inside a template, simply by adding the &jwc; attribute to
+Components can be placed anywhere inside a template, simply by adding the &jwcid; attribute to
any existing tag. For example:
<example>
@@ -146,7 +146,7 @@
The point of all this is that the HTML template should preview properly in a WYSIWYG HTML editor. Unlike
&Velocity; or JSPs, there are no strange directives to get in the way of a preview (or necessitate
a special editting tool), Tapestry hides what's needed inside existing tags; at worst, it adds
-a few non-standard attributes (such as &jwc;) to tags. This rarely causes a problem with most HTML editors.
+a few non-standard attributes (such as &jwcid;) to tags. This rarely causes a problem with most HTML editors.
</para>
<para>
@@ -271,9 +271,9 @@
<para>
Each component declares a list of reserved names using the &spec.reserved-parameter; element; these
-are names which are not allowed as informal parameters, because the component generates the
+are names which are not allowed as informal parameters, because the component generates
the named attribute itself, and doesn't want the value it writes to be overriden by an informal
-parameters. For example, the &DirectLink; component reserves the name "href" ... putting an
+parameter. For example, the &DirectLink; component reserves the name "href" ... putting an
<literal>href</literal> attribute in the HTML template is simply ignored (again, presumed to
be there to support WYSIWYG preview). Case is ignored when comparing attribute names to reserved names.
</para>
1.8 +2 -2 jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml
Index: TapestryUsersGuide.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/UsersGuide/TapestryUsersGuide.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- TapestryUsersGuide.xml 18 Aug 2003 22:25:19 -0000 1.7
+++ TapestryUsersGuide.xml 2 Sep 2003 16:38:13 -0000 1.8
@@ -66,7 +66,7 @@
<!ENTITY WEB-INF '<filename>WEB-INF</filename>'>
-<!ENTITY jwc '<literal>jwc</literal>'>
+<!ENTITY jwcid '<literal>jwcid</literal>'>
]>
<!-- Conventions:
1.21 +45 -61 jakarta-tapestry/doc/src/ContributorsGuide/ContributorsGuide.xml
Index: ContributorsGuide.xml
===================================================================
RCS file: /home/cvs/jakarta-tapestry/doc/src/ContributorsGuide/ContributorsGuide.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- ContributorsGuide.xml 21 Apr 2003 15:39:20 -0000 1.20
+++ ContributorsGuide.xml 2 Sep 2003 16:38:14 -0000 1.21
@@ -160,12 +160,6 @@
</tip>
</para>
-<para>
-Tapestry has some additional, external dependencies on libraries that (due to
-licensing conflicts) are not supplied in the distribution or stored in CVS.
-More details available shortly ....
-</para>
-
<section id="building.subprojects">
<title>Tapestry Subprojects</title>
@@ -253,15 +247,6 @@
</varlistentry>
<varlistentry>
- <term><filename>doc/src/Tutorial</filename></term>
- <listitem>
- <para>
- Builds the Tapestry Tutorial documentation.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><filename>doc/src/DevelopersGuide</filename></term>
<listitem>
<para>
@@ -528,8 +513,9 @@
<para>
The Clover report executes from the <filename>junit</filename> directory, using the Ant
-target <literal>clover</literal>. It runs builds the clover-enhanced version of the framework
-classes, and executs the JUnit test suite twice (with all logging enabled and all logging disabled),
+target <literal>clover</literal>. It builds the clover-enhanced version of the framework
+classes, and executes the JUnit test suite twice (with all logging enabled and
+then with all logging disabled),
then generates the HTML report into the
<filename>web/doc/clover</filename> directory.
</para>
@@ -572,14 +558,13 @@
<title>Type Comment</title>
<programlisting>
/**
- * <replaceable>A useful description of the class or interface, especially covering</replaceable>
- * <replaceable>how it is used, and what other classes or interfaces it interacts with.</replaceable>
- *
- * @author <replaceable>Your Name</replaceable>
- * @version $Id$
- * @since <replaceable>Version</replaceable>
+ * <replaceable>A useful description of the class or interface, especially covering</replaceable>
+ * <replaceable>how it is used, and what other classes or interfaces it interacts with.</replaceable>
*
- **/
+ * @author <replaceable>Your Name</replaceable>
+ * @version $Id$
+ * @since <replaceable>Version</replaceable>
+ */
</programlisting>
</figure>
@@ -656,18 +641,13 @@
</para>
<para>
-And don't forget to make liberal use of JavaDoc links (<literal>@link</literal>) which makes the
-documentation far eaiser to use.
+Also document any cases where a parameter is allowed to be null, or a return value may be null.
</para>
-<note>
- <title>Javadoc Formatting</title>
- <para>
- The standard for formatting Javadoc comments in Tapestry is to close the comment
- with <literal>**/</literal>. You should attempt to follow this, especially
- when modifying existing code.
- </para>
-</note>
+<para>
+And don't forget to make liberal use of JavaDoc links (<literal>@link</literal>) which makes the
+documentation far easier to use.
+</para>
</section>
@@ -709,7 +689,7 @@
<para>
Standard Java guidelines are expected to be followed.
Class names are capitalized (example: <classname>MyClass</classname>).
-Methodsstart with a lower-case character (example: <literal>myMethod</literal>).
+Methods start with a lower-case character (example: <literal>myMethod</literal>).
</para>
<para>
@@ -1173,35 +1153,35 @@
<title>Component Documentation Template</title>
<programlisting>
/**
- * <replaceable>Type comment documentation ...</replaceable>
+ * <replaceable>Type comment documentation ...</replaceable>
*
- * <p><table border=1>
- * <tr>
- * <th>Parameter</th>
- * <th>Type</th>
- * <th>Direction</th>
- * <th>Required</th>
- * <th>Default</th>
- * <th>Description</th>
+ * <p><table border=1>
+ * <tr>
+ * <th>Parameter</th>
+ * <th>Type</th>
+ * <th>Direction</th>
+ * <th>Required</th>
+ * <th>Default</th>
+ * <th>Description</th>
* </tr>
*
- * <tr>
- * <td><replaceable>name</replaceable></td>
- * <td><replaceable>{@link Type}</replaceable></td>
- * <td><replaceable>in|out|in-out</replaceable></td> <co id="procedures.component-doc.direction"/>
- * <td><replaceable>yes|no</replaceable></td>
- * <td><replaceable>Default value</replaceable></td> <co id="procedures.component-doc.default"/>
- * <td><replaceable>Full description</replaceable></td>
- * </tr>
+ * <tr>
+ * <td><replaceable>name</replaceable></td>
+ * <td><replaceable>{@link Type}</replaceable></td>
+ * <td><replaceable>in|out|in-out</replaceable></td> <co id="procedures.component-doc.direction"/>
+ * <td><replaceable>yes|no</replaceable></td>
+ * <td><replaceable>Default value</replaceable></td> <co id="procedures.component-doc.default"/>
+ * <td><replaceable>Full description</replaceable></td>
+ * </tr>
*
- * ...
+ * ...
*
- * <p>Informal parameters are <replaceable>[not]</replaceable> allowed. The component
- * may <replaceable>[not]</replaceable> contain a body.
+ * <p>Informal parameters are <replaceable>[not]</replaceable> allowed. The component
+ * may <replaceable>[not]</replaceable> contain a body.
*
- * ...
+ * ...
*
- **/
+ */
</programlisting>
<calloutlist>
<callout arearefs="procedures.component-doc.direction">
@@ -1247,8 +1227,8 @@
<para>
Run JUnit tests before
doing a checkin.
-You should always have a SourceForge bug or feature request.
-When checking code in, use the SourceForge request as the checkin comment.
+You should always have a Bugzilla bug or feature request.
+When checking code in, use the Bugzilla bug id as the checkin comment.
</para>
<example>
@@ -1307,6 +1287,10 @@
<para>
All source code stored in the repository must contain the standard Apache copyright and license. A copy of the
license, as a comment block, is stored as <filename>support/license.txt</filename>
+</para>
+
+<para>
+Realize that you are assigning copyright to the Apache Software Foundation.
</para>
<para>