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

[Derek Longmuir <dl...@echoworx.com>]

Hi Bryan and John,

I have created something like this with XSL that converts the (old)
action.xml and (new) struts-config.xml files and produces a graph showing
the various forwards, forms, actions, etc. I then use dot to convert the
graph into a gif.

It isn't quite as enlightening as I thought it would be, but certainly
produces interesting pictures. :-) This is primarily due to the fact that
the struts-config.xml doesn't hold all the information - I think to produce
a better overview you would have to also parse the corresponding JSPs for
their tags, and maybe even the action classes themselves. 

I was planning on refining it a little more before releasing it to the list,
but I'll work on getting it up on a web page in the next couple of days for
you. John, maybe you can take it and add what you think is missing. :-)

Thanks, Derek.


-----Original Message-----
From: Brugge, John [mailto:jbrugge@Kraft.com]
Sent: Monday, March 19, 2001 9:56 AM
To: 'struts-user@jakarta.apache.org'
Subject: RE: How can a Struts Action developer best document the system fo r
a JSP developer?


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