Javadoc is next for me once I've got a couple more bug fixes done.
Eddie
Richard Feit wrote:
Thanks Jeremiah.
- For #2, I've filed http://issues.apache.org/jira/browse/BEEHIVE-525
- For #8, I filed a more general bug: http://issues.apache.org/jira/browse/BEEHIVE-524
Rich
Jeremiah Johnson wrote:
I have asked about JavaDoc in the past, but the JavaDocs weren't a priority at that time. As the release of Beehive is drawing near, I made a list of some gaps in the JavaDocs that I think are of particular concern. Please take a look at the list and let me know if you disagree with anything on it. If there aren't any objections, I will create Jira tasks for each.
Note that I focused on stuff that I think end-users of Beehive will be looking for rather than future developers of Beehive itself. I think that end-users are less likely to have patience to look to the code for answers.
1. org.apache.beehive.netui.databinding.datagrid.api generally
needs docs, but there are 5 key classes
* DataGridStateFactory * DataGridState * PagerModel * SortModel * FilterModel
2. Jpf annotations need more detail; here are some key areas from
my perspective
- Action - useFormBean could use a little more detail; preventDoubleSubmit needs details about how it works because the two sentences in the current description seem contradictory; catches could say a bit more; the description on the annotation will likely mean nothing to most future Beehive users (says 'was jpf:action')
- ActionOutput - required and typeHint should have descriptions
- Catch - I think that this would benefit from an example and a description
- ExceptionHandler - common issue with the description (this one says 'was jpf:exception-handler'); tell why readOnly exists
- Forward - actionOutputs, outputFormBean, and externalRedirect, and redirect could all use descriptions
- MessageBundle - put a description on bundlePath at a minimum stating what the base is when a relative path is used
- SimpleAction - give it a description and put a description on conditionalForwards
- seems like the Validate annotations could all use some docs
3. key netui tag libraries need details
* in general, the dir attribute just says 'the dir';
should say 'the text direction' or 'the inherited i18n dir' to be clear * netui:anchor needs corrections in description
* netui:body should specify why it should be used (as
netui:html does) * netui:checkBoxGroup and netui:radioButtonGroup have
great examples, but attributes need descriptions; particularly,
dataSource, optionsDataSource, and repeater; they could just say 'a
String[] to use' so people don't have to wonder if String[] is the only
supported data source type
* netui:checkBoxOption needs info in defaultValue
attribute - or is this a bug? * netui:exceptions needs description in
showDevModeStackTrace attribute; description should say how to turn dev
mode on / off * netui-data:dataGrid attributes need descriptions; should
specify default pager used unless configurePager specified
4. Control annotation ControlInterface defaultBinding needs a
description 5. javax.jws and javax.jws.security - a few classes and methods
have corrupt characters in the descriptions 6. javax.jws.soap the constants needs descriptions 7. org.apache.beehive.controls.api.bean.Controls needs more
detailed description - like who is expected to use this class 8. org.apache.beehive.netui.util.ServletUtils needs more detailed
description - like should this be used by Page Flow developers 9. org.apache.beehive.wsm.axis.ant.AxisTypeGeneratorTask needs docs
10. org.apache.beehive.wsm.axis.AxisHook needs docs
Thanks.
- jeremiah
