RE: How can a Struts Action developer best document the system fo r a JSP developer?

["Brugge, John" <jb...@Kraft.com>]

Bryan,

You might check out a recent article on JavaWorld called "Doclet your
Servlet"
(http://www.javaworld.com/javaworld/jw-03-2001/jw-0302-doclets.html) that
describes a custom doclet that understands some custom doc tags. It would
probably take some customization to work with Struts Actions, since it looks
like it uses introspection to look for instances of true servlets.

I've been thinking of the same problem, and think that you could get pretty
good mileage out of a simple XSL template that transformed the
struts-config.xml into a clearer HTML description of the actions, their
navigation and form expectations. It could handle #2 and #3 below easily; #4
and #5 would be harder. You could even tie this into the JavaDoc of the
ActionForms by creating links from the form names to the area where your
JavaDoc lives.

I'm not an XSL expert, but I've done some transforms before and figure this
wouldn't take very long to create - the key for me is just finding the time
now ;-). If I come up with something, I'll forward it to the group, unless
someone beats me to it.

John


> -----Original Message-----
> From:	Bryan Field-Elliot [SMTP:bryan_lists@netmeme.org]
> Sent:	Saturday, March 17, 2001 6:12 PM
> To:	struts-user@jakarta.apache.org
> Subject:	How can a Struts Action developer best document the system
> for a JSP developer?
> 
> I am struggling right now with how to properly and efficently document 
> my Struts application for my JSP developer (who is by no means a Java 
> expert). Specifically, I want to document each Action as well as each 
> ActionForm that I code, including things like:
> 
> 1. the pages I expect the user to have come from
> 2. the pages to which I might forward, or redirect, the user after 
> completing the action
> 3. The beans I expect to be in place prior to submitting to my action
> 4. The beans I will set up with values for the resulting JSP page to 
> work with
> 5. The errors (<html:errors>) I may set up
> 
> And anything else that might be appropriate. I'd like to do so in a way 
> that lets me rely on Javadoc, so that I can keep my documentation inside 
> my code. Javadoc when used correctly will also let me do things like 
> "see also" the Bean documentation (from the Action documentation).
> 
> I am curious if anyone has developed a "template" action or bean, which 
> makes best use of Javadoc and which I can cut-and-paste at the head of 
> every one of my Action classes, etc?
> 
> Thanks,
> Bryan