xdocs/jellydoc.xml (79 lines of code) (raw):
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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="dev@commons.apache.org">Apache 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://commons.apache.org/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://commons.apache.org/patches.html'>contributing patches</a>.
</p>
<p>
<strong>Note</strong> that this document is based on the maven build script used by
the Apache 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>