| <?xml version="1.0"?> |
| <!-- |
| Copyright 2002,2004 The Apache Software Foundation. |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document> |
| <properties> |
| <title>A Guide To JellyDoc</title> |
| <author email="commons-dev@jakarta.apache.org">Jakarta Commons Development Team</author> |
| </properties> |
| |
| <body> |
| <section name='Introduction'> |
| <subsection name="But What Is JellyDoc?"> |
| <p> |
| <strong>JellyDoc</strong> generates documentation for <strong>Jelly</strong> |
| tag libraries from their javadoc. An example of JellyDoc generated content can be viewed |
| <a href='http://jakarta.apache.org/commons/jelly/libs/betwixt/tags.html'>here</a>. |
| </p> |
| </subsection> |
| <subsection name='So What Is The Document?'> |
| <p> |
| This document is a brief (and non-normative) |
| guide written by developers using JellyDoc to document their tag libraries and is |
| aimed at helping developers use JellyDoc. Please help to improve this resource |
| by <a href='http://jakarta.apache.org/commons/patches.html'>contributing patches</a>. |
| </p> |
| <p> |
| <strong>Note</strong> that this document is based on the maven build script used by |
| the Jakarta Commons Jelly build. Details may vary for other builds. |
| </p> |
| </subsection> |
| </section> |
| <section name='An Anatomy Of A Tag Library Description'> |
| <p> |
| The content generated by JellyDoc can be divided into different sections. These sections |
| are then arranged into the document presented to the user. Understanding where each |
| of these sections comes from is key to writing javadocs for tag libraries aimed at use |
| by JellyDoc. |
| </p> |
| <subsection name='Tag Library Short Description'> |
| <p> |
| This is not strictly part of the main JellyDoc generated document but it is related |
| (and this seems like a good place to discuss it). This appears in the generated overview |
| document as the content paragraph. |
| </p> |
| <p> |
| This is taken from the <code><description></code> tag in the <code>project.xml</code> |
| for the tag library. |
| </p> |
| </subsection> |
| <subsection name='Tag Library Long Description'> |
| <p> |
| This appears in the main generated JellyDoc content as the description associated with |
| the library in the library table and also within the descriptive subsection below. |
| </p> |
| <p> |
| This is the contents of the body of the <code>package.html</code> file for the package |
| containing the tag library. |
| </p> |
| </subsection> |
| <subsection name='Tag Description'> |
| <p> |
| This appears in the main generated JellyDoc content as the description associated with |
| the tag in the tags table and also within the descriptive subsection for the tag. |
| </p> |
| <p> |
| This is the contents of the class level javadocs for the class implementing the class. |
| </p> |
| </subsection> |
| <subsection name='Attribute Description'> |
| <p> |
| This appears in the main generated JellyDoc content as the description associated with |
| the attribute in the tag attributes table. |
| </p> |
| <p> |
| This is the contents of the javadocs for the setter property mapped to the attribute. |
| Note that this includes the contents of the <code>@return</code> tag and so care |
| is needed to ensure that the generated output scans. |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |
| |
