XDoclet: Attribute-Oriented Programming - Developer Guide

##### XDoclet

- Overview
- News and Status
- Download/Installation
- Using XDoclet
- Best Practices
- FAQ
- License

##### Ant Task Reference

- <doclet .. />
- <ejbdoclet .. />
- <hibernatedoclet .. />
- <jdodoclet .. />
- <jmxdoclet .. />
- <mockdoclet .. />
- <portletdoclet .. />
- <springdoclet .. />
- <tapestrydoclet .. />
- <webdoclet .. />
- <wseedoclet .. />

##### Tag Reference

- apache (@soap @struts @axis @tapestry)
- bea (@weblogic)
- borland (@bes)
- caucho (@resin)
- ejb (@ejb @dao)
- exolab (@castor)
- hp (@hpas)
- hibernate (@hibernate)
- ibm (@websphere)
- java (@javabean)
- jboss (@jboss)
- jdo (@jdo)
- jmx (@jmx)
- jsf (@jsf)
- macromedia (@jrun)
- mockobjects (@mock)
- mvcsoft (@mvcsoft)
- mx4j (@mx4j)
- objectweb (@jonas)
- oracle (@oc4j)
- orion (@orion)
- portlet (@portlet)
- pramati (@pramati)
- spring (@spring)
- sun (@sunone)
- sybase (@easerver)
- tjdo (@tjdo)
- web (@web @jsp)
- webwork (@webwork)
- wsee (@wsee)
- xdoclet (@xdoclet @doc @msg)

##### Feature Documentation

- Using Value Objects
- EJB Environment Handling

##### Advanced

- Maven Plug-in
- Merge Points
- IDE Integration
- Migration from EJBDoclet
- Ant 1.5 Troubleshooting

##### Community

- Feedback
- Resources
- Tools

##### Development

- Developer Guide
- Javadoc (API)
- Template Language (*.xdt)
- XJavaDoc Site

##### Search XDoclet

##### Project Documentation

- About XDoclet
- Project Info
- Project Reports
- Development Process

## Developer Guide

### New XDoclet Developer? Welcome!

There are a variety of ways to participate. Regardless of how you choose to participate, we suggest you to join the mailing list first.

A first step in praticipating is usually to provide patches or other contributions to entries in the issue tracking system.

Feel the irresistible urge to write quality code? Then join the XDoclet project team today (send an email to the xdoclet-devel mailing list)!

### Coding Conventions

Below is a list of coding conventions that are specific to XDoclet, everything else not specifically mentioned here should follow the official Sun Java Coding Conventions.

1. Brackets that begin and end classes and methods should begin and end on a new line and should exist even for one line statements.

2. 4 space indent. NO tabs. Period. We understand that many developers like to use tabs, but the fact of the matter is that in a distributed development environment where diffs are sent to the mailing lists by both developers and the version control system (which sends commit log messages), the use tabs makes it impossible to preserve legibility.

3. JavaDoc MUST exist on all methods. If your code modifications use an existing class/method/variable which lacks JavaDoc, it is required that you add it. This will improve the project as a whole.

4. If you contribute to a file (code or documentation), add yourself to the authors list at the top of the file. Your sourceforge email address is preferred. Do not include the @ sign, as email spiders will put your email in spam lists. For java files the preferred Javadoc format is:

    @author <a href="mailto:user at domain.com">John Doe</a>

Thanks for your cooperation.

### Commits

Before commiting at least rebuild xdoclet to see if the changes at least compile.
This will also run a beautifier over your java files. Sync your IDE after the build was run to grab those format changes and only commit afterwards.

If possible, run the build in the samples directory over your changes and see if this passes. This is no real testsuite, but the build run should not stop. If possible add some tags for what you are testing to the samples and see if it behavs as desired.

### JIRA

As you already know, JIRA is used as issue tracking system. As there is a link between JIRA and sourceforge, you should do two things:

- Set your sourceforge email address (xxx@users.sourceforge.net) as email address in JIRA
- For commits that link to items in JIRA, add the issue number (e.g. XDT-399) to the commit message.

When you plan to work on an issue, assign the issue to yourself, so other developers won't grab it as well and duplicate work is done. If you see that you won't solve the problem, then assign the issue back to xdoclet-devel general user.

If there is an issue assigned to another developer for a long time without any notion of activity and you have a solution to the issue, you can take over the issue and apply your fix.

If you plan to do bigger changes (more severe than e.g. fixing a typo, throwing out unused imports etc.) and there is no JIRA for it, create one. This is generally a good idea, as the change log is built from the closed JIRA issues.

As the changelog for a release is created from the JIRA issues, set the release an issue was fixed when closing a successful fix and select no release when rejecting an issue (e.g. incomplete).

The resolved state in JIRA should only be used to signal that the problem itself is solved (and the fix applied), but there is some feedback from the submitter needed. If an issue is solved, then close it completely.

### Further Reading

- Architecture
- Branches and Tags
- Planning